Luma MCP Server

The Luma MCP Server gives approved AI assistants structured, governed access to Luma patient data and operational workflows. Using the Model Context Protocol, it lets clinical and operational staff query patient context, manage appointments, work referrals, and coordinate care — directly from their AI client — without leaving Luma's authorization and audit boundary.

Luma governs all access. The MCP server enforces which tools are available, what data is returned, and which operations are permitted. The AI assistant is a client of that boundary, not an authority within it.

Early Access

Luma MCP is available in early access. The hosted MCP endpoint supports OAuth authorization-code sign-in with PKCE for interactive remote clients. Existing integrations that already use a Luma API token in the x-access-token header remain supported; that legacy token flow is separate from OAuth.

HIPAA / Healthcare Data

Please review the data privacy section before using this MCP as this MCP deals with HIPAA controlled healthcare data.

Prerequisites

A Luma account with access to the organization and workflows you intend to use
An MCP client that supports remote MCP over HTTPS and OAuth authorization-code sign-in with PKCE (for Claude, use a remote/custom connector when that capability is enabled for your workspace)
Approval from your organization to connect that AI client to healthcare data under your policies and applicable agreements

Access control and governance

Before connecting, understand what Luma controls at the server level:

Tool availability is scoped. Not all tools are enabled for every account. Luma determines which tools are exposed based on your configuration.
Data returned is scoped. Responses contain only information available within the scope of the authenticated account. Contact details, full dates of birth, and insurance member numbers are minimized or omitted even where the underlying data exists.
Mutating operations require the same authorization as any Luma API call. Tools that create, update, or cancel records perform those operations in Luma with the permissions of the authenticated token.
All tool calls are logged with timestamps, resource IDs, and session context. See Data privacy for what is and is not captured in audit logs.

On client selection: Some Luma tools return PHI including patient names and MRNs. Only connect Luma MCP to AI clients and platforms that your organization has approved for handling protected health information under your applicable policies and BAAs.

Quick setup

The Luma MCP Server is hosted at mcp.lumahealth.io. No local installation is required.

In Claude's connector settings, add a remote/custom MCP connector (see Anthropic's setup guide) and set its server URL to:

https://mcp.lumahealth.io/mcp

Choose OAuth sign-in. Claude registers as a public OAuth client automatically; you do not need to request or enter a Luma client_id or client_secret. The browser opens Luma sign-in. Sign in with your Luma email and password and any required one-time code, then review and approve the access request. Organization SSO may appear only when it has been configured for your account. Return to Claude and confirm that Luma tools are listed.

claude mcp add --transport http luma https://mcp.lumahealth.io/mcp

Then run /mcp, choose to authenticate to Luma, complete sign-in and consent in the browser, and return to Claude Code. OAuth handles client registration and token exchange; do not add a static Luma client secret to this configuration.

This local mcp-remote configuration uses the legacy Luma API-token header, not hosted OAuth. Use it only if your organization has specifically chosen token-based configuration for this client. For interactive remote OAuth, use a Claude remote connector that supports OAuth instead.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "luma": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.lumahealth.io/mcp",
        "--header",
        "x-access-token:your-api-token-here"
      ]
    }
  }
}

Restart Claude Desktop. On first run, mcp-remote is downloaded automatically.

The configuration below uses the legacy x-access-token header. Use it only for an integration configured for Luma API-token authentication; OAuth-capable remote clients should use the browser sign-in flow instead.

Add to .cursor/mcp.json or via Cursor Settings → MCP Servers:

{
  "mcpServers": {
    "luma": {
      "type": "http",
      "url": "https://mcp.lumahealth.io/mcp",
      "headers": {
        "x-access-token": "your-api-token-here"
      }
    }
  }
}

In ChatGPT on the web, go to Plugins, select + → Add custom MCP server, and enter the Luma endpoint below. Choose OAuth with dynamic client registration:

https://mcp.lumahealth.io/mcp

Complete Luma sign-in and review the consent screen. No separate Luma API client secret or token-forwarding adapter is required for this OAuth flow. Review the connection warning and install the plugin before using it. Workspace permissions may restrict custom MCP servers; see the OpenAI connection guide for current steps and requirements.

After connecting, start a new chat and select Luma using @ in the prompt box. The standard connector may expose only the default tool set; workflow-specific tools require forwarding the relevant meta header and, for navigator tools, x-assistant-instance-id.

With a demo organization connected, try:

Use Luma to find patient Ronald Moreland and show me their patient profile.

Use Luma to list all schedulable providers.

Use Luma to find the next unconfirmed appointment and show the patient and provider details.

These prompts use the default tool set. For workflow-specific tools, a client must also forward the relevant meta header and, for navigator tools, x-assistant-instance-id.

For a remote client that supports OAuth authorization-code sign-in with PKCE, connect to the hosted endpoint and complete the browser sign-in and consent flow:

URL: https://mcp.lumahealth.io/mcp

The MCP endpoint publishes OAuth discovery metadata and registers public clients dynamically. It requires PKCE and the luma:access scope. Clients that cannot use OAuth may use the legacy x-access-token header only when configured with a valid Luma API JWT. Never put credentials in the connection URL, and never send a client_secret as the x-access-token value.

Authentication

OAuth for hosted remote clients

The hosted MCP endpoint uses OAuth authorization-code flow with S256 PKCE and dynamic public-client registration. No client secret or client_credentials grant is used for this MCP flow. A person signs in to Luma and explicitly approves the connection; the Luma session determines the account access available to the MCP session.

The consent covers the tools available to the signed-in Luma account, including available write actions. OAuth does not create a read-only role or grant a narrower per-tool scope. Review the requested access before approving it.

OAuth access tokens last at most 15 minutes and are refreshed by the client when supported. The authorization grant expires after eight hours, and the underlying Luma session is revalidated; you may need to sign in and consent again after expiry or revocation.

Existing API-token integrations

The server continues to accept an existing Luma API JWT in the x-access-token header for integrations configured to use that legacy flow. This is separate from MCP OAuth: OAuth access tokens use Authorization: Bearer, while x-access-token is for a Luma API JWT. If your setup specifically requires API-token authentication, follow the credential and token-exchange steps in the Luma REST API documentation. Do not paste a client secret directly into MCP configuration.

Access and token security

The available tools and data follow the authenticated Luma account and configuration. Some tools can modify records. Only connect an AI client approved by your organization for the intended data, protect any credentials used by legacy integrations, and revoke or rotate them if exposed.

Available capabilities

Tools are organized by the workflows they support. Tools that retrieve data are marked Read; tools that create or modify records are marked Write.

Patient context

Tool		Description
`search_patients`	Read	Find patients by name, date of birth, phone number, or ID
`get_patient`	Read	Get a patient's full profile by ID
`update_patient_demographics`	Write	Update name, date of birth, gender, race, ethnicity, and other demographic fields

Scheduling & appointments

Tool		Description
`search_appointments`	Read	Find appointments by patient, provider, facility, status, or date range
`get_appointment`	Read	Get full appointment details by ID
`list_reschedule_slots`	Read	Get available slots a specific appointment can be rescheduled into
`list_open_slots`	Read	Get open availability slots from the scheduler
`search_waitlists`	Read	Find waitlist entries by patient, provider, facility, or status
`confirm_appointment`	Write	Confirm a scheduled appointment
`cancel_appointment`	Write	Cancel an appointment, with optional cancellation reason
`reschedule_appointment`	Write	Move an appointment into a new availability slot
`book_open_slot`	Write	Book an open slot for a patient
`create_waitlist`	Write	Add a patient to the waitlist for an earlier opening
`update_waitlist`	Write	Update a waitlist entry's status, provider, or facility preference

Referrals

Tool		Description
`search_referrals`	Read	Search inbound referrals by status, provider, patient, or date range
`search_inbound_referrals`	Read	Advanced inbound referral search with complex filters
`get_referral`	Read	Get full inbound referral details by ID
`search_outbound_referrals`	Read	Search outbound referrals by status, provider, or facility
`get_outbound_referral`	Read	Get full outbound referral details by ID
`create_referral`	Write	Create a new inbound referral
`update_referral`	Write	Update an existing inbound referral
`create_outbound_referral`	Write	Create a new outbound referral
`update_outbound_referral`	Write	Update an existing outbound referral

Recalls

Tool		Description
`search_recalls`	Read	Find patients due for a recall, filterable by status, provider, and facility
`get_recall`	Read	Get full recall details by ID

Insurance & eligibility

Tool		Description
`list_patient_insurances`	Read	List insurance policies on file for a patient
`list_patient_insurance_verifications`	Read	List the full eligibility verification history for a patient
`get_insurance_verification`	Read	Retrieve a specific eligibility verification result
`list_insurance_payors`	Read	Search for insurance payers by name
`list_patient_copays`	Read	List appointments with associated copay amounts
`list_billing_charges`	Read	List billing charges by patient or appointment
`create_patient_insurance`	Write	Add a new insurance record for a patient
`update_patient_insurance`	Write	Update an existing insurance record
`check_insurance_eligibility`	Write	Run a real-time eligibility check with the payer
`upsert_billing_charges`	Write	Save or update billing charges for an appointment

Feedback

Tool		Description
`search_feedback`	Read	Search patient feedback and NPS scores by patient, provider, facility, or date range
`create_net_promoter_score`	Write	Record an NPS score for an appointment

Messaging & staff follow-up

Tool		Description
`list_messages`	Read	List messages sent to or from a patient across all channels
`get_settings`	Read	Retrieve account-level settings and configuration
`send_staff_message`	Write	Send an internal staff note about a patient, visible only to the care team
`create_action_queue_item`	Write	Add a manual follow-up task to the action queue for a patient

Providers & facilities

Tool		Description
`list_providers`	Read	List providers with optional facility and schedulable filters
`get_provider`	Read	Get provider details by ID
`get_facility`	Read	Get facility details by ID

Agent Launchpad workflows and enrollments

Agent Launchpad workflows are configured jobs. A run is one patient's execution of a job; a patient may have more than one run. These two read-only tools are included in the default tool set and in the agent-launchpad-workflows meta selector. They do not enroll patients or start workflows.

Tool		Description
`agentlaunchpad_list_workflows`	Read	List the account's configured jobs, with workflow IDs, names, status, objectives, and a continuation cursor
`agentlaunchpad_list_workflow_enrollments`	Read	List enrolled patients or individual runs for a workflow, with active/history, status, and patient filters

List available jobs

Call agentlaunchpad_list_workflows first to obtain a workflowId. This lists configured jobs, including paused and archived jobs unless filtered; it does not list templates or drafts.

Argument	Default	Description
`status`	All statuses	Optional `active`, `paused`, or `archived`
`limit`	`25`	Page size, from 1 to 100
`cursor`	First page	Pass the previous response's `nextCursor` to continue

The response contains items and nextCursor. Each item has workflowId, name, status, and objective. Continue until nextCursor is null; the final page can be empty.

List enrolled patients or runs

Call agentlaunchpad_list_workflow_enrollments with the chosen workflowId.

Argument	Default	Description
`workflowId`	Required	Job ID returned by `agentlaunchpad_list_workflows`
`scope`	`active`	`active` for in-flight runs; `all` includes historical runs
`view`	`patients`	`patients` groups matching runs by patient; `runs` returns each matching execution
`statuses`	No additional filter	Optional nonempty array of exact run statuses
`patientId`	All patients	Optional patient ID to restrict results
`page`	`1`	Page number, starting at 1
`limit`	`25`	Page size, from 1 to 100

Active statuses are pending, running, waiting, stalled, and escalated. Historical statuses also include completed, failed, and canceled. Status filters intersect with scope: use scope: "all" to find completed, failed, or canceled runs.

To see	`scope`	`view`
Unique patients currently enrolled	`active`	`patients`
All current executions	`active`	`runs`
Unique patients ever enrolled in the workflow	`all`	`patients`
All historical and current executions	`all`	`runs`

The response contains items, total, page, limit, and hasMore, along with the selected workflow, scope, and view. Patient results include patientId, patientName, matchingRunCount, and latestMatchingRun. Run results include runId, patient ID/name, status, and created/started/completed timestamps. Patient grouping happens after filtering and before pagination; counts and the latest run refer only to matching runs. Results are ordered by newest matching run first. Deleted and simulation runs are excluded.

For example, to list completed runs for a job, use its ID in place of this synthetic example:

{
  "workflowId": "507f1f77bcf86cd799439011",
  "scope": "all",
  "view": "runs",
  "statuses": ["completed"],
  "page": 1,
  "limit": 25
}

Enrollment listing scans at most 10,000 upstream runs, with a 20-second scan budget and a 10-second timeout per request. These limits apply before patient/status filtering. If a limit is exceeded, the tool returns an error rather than incomplete totals. Concurrent enrollment changes can affect pagination; retry if the tool reports that the history changed during the scan.

Example prompts:

List the active Agent Launchpad workflows available to my account.

For that workflow, list unique patients currently enrolled.

Show all completed runs for that workflow, including historical enrollments.

Advanced EHR operations

These tools operate directly against your connected EHR. They are typically used in automated workflows and agent pipelines rather than conversational queries.

Tool		Description
`ehr_list_availabilities`	Read	Query available appointment slots from the EHR
`ehr_list_patient_orders`	Read	Retrieve a patient's active orders from the EHR
`ehr_get_patient_next_contact_sync`	Read	Get the next scheduled contact sync date for a patient
`ehr_create_appointment`	Write	Create an appointment in the EHR
`ehr_confirm_appointment`	Write	Confirm an appointment in the EHR
`ehr_cancel_appointment`	Write	Cancel an appointment in the EHR
`ehr_create_encounter`	Write	Create a clinical encounter record in the EHR
`ehr_write_form_field`	Write	Write mapped patient form answers back to the EHR
`ehr_import_patients`	Write	Import patients from the EHR by demographics
`ehr_sync_patient`	Write	Sync a patient record from the EHR
`ehr_sync_patient_appointments`	Write	Sync a patient's appointment list from the EHR
`ehr_reload_patient`	Write	Force-reload a patient record from the EHR
`ehr_reload_patient_appointments`	Write	Force-reload a patient's appointments from the EHR

Verifying the connection

Once configured, ask a question that requires a live Luma lookup:

You:   Show me unconfirmed appointments for tomorrow.
Agent: [calls search_appointments → returns matching appointments]

You:   Which inbound referrals are incomplete or past due?
Agent: [calls search_referrals with status filters → returns results]

You:   Check the waitlist for Jane Smith's appointment
       and reschedule if there's an earlier slot.
Agent: [calls search_waitlists, list_reschedule_slots, reschedule_appointment]

Two indicators that the connection is working:

Your client's tools or MCP panel lists Luma tools
The agent makes explicit tool calls rather than responding from general knowledge

Data privacy

See the Privacy Policy Addendum for data categories, uses, recipients, retention, and user controls. It supplements Luma’s HIPAA policies.

Important Data Privacy Warnings

By using this MCP server, you acknowledge and agree to the following:

PHI Access Controls: By using this MCP you represent that you have taken the appropriate steps to control LLMs coming into contact with Protected Health Information (PHI).
Business Associate Agreement: By using this MCP you represent that you have a Business Associate Agreement (BAA) and appropriate security controls with your LLM provider.
LLM Limitations: LLMs make mistakes. Use caution and discipline when using data from this MCP with an LLM, especially in any care setting.
Data Redaction Limitations: Sensitive data redaction is best effort and not guaranteed. You are responsible for your own data privacy.

The Luma MCP Server applies the following minimization controls to all responses:

Contact information is not returned. Phone numbers and email addresses are replaced with hasPhone / hasEmail boolean flags.
Full date of birth is not returned. Only birth year is exposed.
Insurance member numbers are not returned. Member IDs (which may be SSN-derived) are stripped from all responses.
Medical record numbers are not returned. medicalRecordNumber is redacted from patient responses.
Patient names are returned where operationally required. These are PHI under HIPAA. Handle all data returned by the server according to your organization's HIPAA obligations and applicable privacy controls.
Tool calls are audit-logged with timestamps, resource IDs, and session context. Logs are designed to avoid capturing PHI, but are not a substitute for your organization's own privacy controls and compliance review.

Luma MCP does not currently attribute individual tool calls to a named human user. Attribution is at the token level.

Troubleshooting

Symptom	Cause	Resolution
`No access token provided`	A legacy-token integration is missing its `x-access-token` header	Add the Luma API JWT to the `headers` block; for OAuth, reconnect and complete browser sign-in
`401 Unauthorized`	OAuth access or refresh token is expired/invalid, or a legacy token is invalid or scoped to a different account	Reconnect and complete Luma sign-in; for legacy token authentication, replace the invalid Luma API JWT
No Luma tools appear	Client loaded before the config was saved	Restart the client; in Claude Code run `/mcp` to verify
`Unknown tool` error	Tool name not recognized by the server	Contact Luma support — the server version may have changed
Connection refused or timeout	Client cannot reach `mcp.lumahealth.io`	Confirm outbound HTTPS to `mcp.lumahealth.io` is allowed on your network

Next steps

Full tool reference — input parameters, required fields, and example responses for every tool
Scoped tool sets — restrict which tools are exposed for a specific workflow using the meta request header
Luma API documentation — direct REST API access for custom integrations

Prerequisites​

Access control and governance​

Quick setup​

Authentication​

OAuth for hosted remote clients​

Existing API-token integrations​

Available capabilities​

Patient context​

Scheduling & appointments​

Referrals​

Recalls​

Insurance & eligibility​

Feedback​

Messaging & staff follow-up​

Providers & facilities​

Agent Launchpad workflows and enrollments​

List available jobs​

List enrolled patients or runs​

Advanced EHR operations​

Verifying the connection​

Data privacy​

Troubleshooting​

Next steps​