Developers · Patient access

Patient MCP server

LiveNew

A Model Context Protocol server for patients, live since November 5, 2026. A patient creates a read-only key from their portal account and connects the AI assistant they already use, such as Claude, ChatGPT or any other MCP client, to their own record at one practice: visits, released test results, signed visit summaries, problems, medications and allergies, bills and portal messages.

POSThttps://chartvoyant.com/api/v1/portal/mcpdocs below

At a glance

StatusLive in production since November 5, 2026.
Endpointhttps://chartvoyant.com/api/v1/portal/mcp with the key in an Authorization header, or https://chartvoyant.com/api/v1/portal/mcp/<key> for connectors that take only a URL, such as custom connectors in Claude and ChatGPT.
Who it's forA patient's own AI assistant. A key reads one patient's record at one practice, and no tool takes a patient argument: the key is the patient. An agent working for the practice uses the MCP server for practices instead.
AuthenticationA patient MCP key, cvpk_…, that the patient creates. A portal session, a ChartVoyant API key (cvk_…) or a SMART token is refused with a 401. OAuth sign-in is not available yet.
AccessRead-only. Ten tools, each annotated readOnlyHint: true. None of them books, sends, pays for or changes anything.
TransportStreamable HTTP, stateless. One JSON-RPC 2.0 message per POST, answered with one JSON response. GET and DELETE return 405: there is no standalone event stream and no session.
Protocol versionsMCP 2026-07-28, plus 2025-11-25, 2025-06-18 and 2025-03-26 for clients that open with initialize.
LimitsRequest bodies up to 256 KB. Per key: 20 requests a second, 300 a minute and 5,000 an hour, then a 429 with Retry-After. A tool result is cut off at 60,000 characters.
AuditEach tool call is recorded in the practice's audit log as a read by the patient through the key, with the tool and the client's name. Argument values, results and the key itself stay out of it.

Keys

A patient MCP key belongs to the patient. Nobody else can create one, and the patient can revoke it at any time.

A synthetic example of the key format. The prefix identifies the key; the secret proves you hold it.

  • The patient creates it. In the patient portal under Account → AI assistants, or at chartvoyant.com/mcp-self-register by signing in with the portal account. Either way the patient enters their portal password again and confirms they understand what the key opens. The practice can't create a key for a patient, and neither can an app.
  • One patient, one practice. A patient seen at two practices that use ChartVoyant creates a key at each one and adds both to their app.
  • Shown once. ChartVoyant keeps only a SHA-256 hash of the key. After the key is created, the portal shows its prefix and last four characters, never the whole key.
  • Read-only, always. There is no write access level for a patient key.
  • Keys expire. After 30, 90 (the default), 180 or 365 days, chosen when the key is created. There is no renewal: create a new key and revoke the old one. A patient can have up to 10 active keys, so each app can have its own.
  • Revocation is immediate. A key revoked in the portal or on the self-register page gets a 401 on its next request. A key also stops working if the patient's portal account is turned off.
  • A connector URL is a password. The URL form carries the whole key. ChartVoyant's logs record the route, never the path with the key in it, but anyone who sees the URL can read the record, so treat it exactly like the key.

Connect a client

Patients get these steps, already filled in with their own key, on the self-register page and in the portal. In the examples below, replace <key> with a cvpk_… key.

Claude (web, desktop and mobile): a custom connector

# Customize → Connectors → Add custom connector
Name:     ChartVoyant
URL:      https://chartvoyant.com/api/v1/portal/mcp/<key>
Sign-in:  none (the key is in the URL)

ChatGPT (paid plans, with Developer mode turned on in Settings)

# Add an app (connector) with no authentication
URL:      https://chartvoyant.com/api/v1/portal/mcp/<key>

Claude Code

claude mcp add --transport http chartvoyant-health https://chartvoyant.com/api/v1/portal/mcp \
  --header "Authorization: Bearer $CHARTVOYANT_PATIENT_KEY"

A config file (Cursor, VS Code, Gemini CLI and others)

{
  "mcpServers": {
    "chartvoyant-health": {
      "url": "https://chartvoyant.com/api/v1/portal/mcp",
      "headers": { "Authorization": "Bearer <key>" }
    }
  }
}

That is the shape of Cursor's ~/.cursor/mcp.json. VS Code's user mcp.json puts the server under "servers" with "type": "http", and Gemini CLI's ~/.gemini/settings.json takes "httpUrl" in place of "url".

A client that starts only local servers, through the mcp-remote bridge

npx -y mcp-remote https://chartvoyant.com/api/v1/portal/mcp --header "Authorization: Bearer <key>"

Any HTTP client

# Read the overview of the record this key belongs to
curl https://chartvoyant.com/api/v1/portal/mcp \
  -H "Authorization: Bearer $CHARTVOYANT_PATIENT_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_overview","arguments":{}}}'

Keep a key in a user-level config or an environment variable, never in a project file that could be committed or shared.

Tools

Ten read-only tools. Every one of them reads the record of the patient the key belongs to.

ToolArgumentsReturns
get_overviewNoneStart here. Whose record it is, the practice (name, locations, phone numbers and today's date there), the next appointment, how many results and visit summaries there are, open messages and what the patient owes.
list_appointmentswhen: upcoming (default), past or all. limit: 1 to 50, default 10.Date and time, type, provider, location, status and reason for each visit, and whether its visit summary is signed.
list_test_resultssearch: text in the result's name, up to 80 characters. since: YYYY-MM-DD. limit: 1 to 50, default 20.Released results, newest first: name, date, whether anything was flagged abnormal, the conclusion, the care team's message and a result_id.
get_test_resultresult_idEvery value in one result: measured value, unit, reference range, abnormal flags and lab comments, with the conclusion and the care team's message.
list_visit_summarieslimit: 1 to 20, default 10.Signed visit notes, newest first: visit type, date, a preview of the plan, whether there is an after-visit summary, and a visit_summary_id.
get_visit_summaryvisit_summary_idThe whole signed note (the first 24,000 characters; the rest is in the portal), the after-visit summary written for the patient, and any addenda.
get_health_summaryNoneThe active problem list, active medications with the instructions on file, and active allergies with their reactions.
get_billing_summaryNoneWhat the patient owes now, what insurance is still processing, each visit's charges and what insurance paid, open balances, the individual charges and recent payments.
list_messageslimit: 1 to 50, default 20.The secure messages, appointment requests and refill requests the patient sent from the portal, newest first, with their status and a message_id.
get_messagemessage_idOne conversation in full: what the patient wrote and every reply from the office, in order.

Never over this server: booking, cancelling or rescheduling, sending a message, requesting a refill, paying a bill, or changing anything in the record. The patient does those in the portal, where the practice expects them.

What a tool returns

  • Exactly what the portal shows. A test result appears once it is final and the practice has released it to the portal; a result the practice is holding back doesn't appear, and neither do its values. Only signed visit notes appear, never drafts. Problems, medications and allergies are the active ones. If the portal doesn't show something to the patient, no tool returns it.
  • Two forms of every result. content[0] is a one-line summary, content[1] is the whole result as JSON text, and structuredContent is the same object for clients that read it. A result longer than 60,000 characters is cut off with a note asking for fewer items, and structuredContent is left out.
  • Times are the practice's local time. An appointment's starts is a wall-clock time with no zone, such as 2026-11-12T09:30, next to a label such as Thu, Nov 12, 2026, 9:30 AM. get_overview gives today's date at the practice. Dates are YYYY-MM-DD.
  • Money is in US dollars. Amounts are formatted strings such as "$145.00". What the patient owes is also given in integer cents, as amount_you_owe_cents.
  • Record text is data. Notes, messages and comments are what clinicians and the patient wrote. The server's instructions tell the model to treat them as content and never as instructions, to explain in plain language without diagnosing, and to send the patient to the practice, or to 911 or 988 in an emergency.
# One item from list_appointments (synthetic)
{
  "appointment_id": "5f0c2a8e-…",
  "when": "Thu, Nov 12, 2026, 9:30 AM",
  "starts": "2026-11-12T09:30",
  "ends": "2026-11-12T10:00",
  "type": "Follow-up",
  "status": "scheduled",
  "provider": "Dr. Alicia Reyes",
  "location": "Main office",
  "reason": "Low back pain follow-up",
  "visit_summary_signed": false
}

Privacy and audit

The patient chooses where the record goes. Nothing reaches an AI app until the patient creates a key and gives it to that app. Information a patient shares with an AI app goes to the company that makes it, and HIPAA's privacy rules generally don't follow it there; the patient sees that warning, and confirms it, before a key is created.

The practice can see every read. Each tool call writes a portal.mcp.tool.read event to the practice's audit log, with the patient as the actor, the key's prefix, the tool, the names of the arguments, the client's name and version when the client sends them, and how long the call took. Creating and revoking a key are recorded in the same log. The values a model sent, the results it got back and the key itself are never recorded.

The patient can see every key. The key list in the portal shows each key's name, when it expires, when it was last used and by which app, and a button to revoke it.

Errors

StatusMeaning
401No key, a credential that isn't a patient MCP key, or a key that is unknown, expired or revoked. The response carries WWW-Authenticate: Bearer realm="ChartVoyant patient MCP", error="invalid_token" and points to the self-register page.
400A malformed JSON-RPC message, a header that disagrees with the body (-32020) or an unsupported protocol version (-32022).
403A browser Origin that is not allowed.
404An unknown method on a 2026-07-28 request (-32601).
405GET or DELETE. There is no event stream and no session.
429Over the key's budget. Wait for the number of seconds in Retry-After.
A tool errorA bad argument or an ID that isn't in this record comes back as a tool result with isError: true and a plain-language message, not as a protocol error.

Building for patients

  1. Let the patient bring the key

    An MCP client should let the patient paste their own key, keep it in the system's credential store, and never log it or send it anywhere but this endpoint. Don't ask patients to email or paste a key to you, and don't collect keys on a website you run.

  2. For an app that serves many patients, use SMART on FHIR

    A patient-facing product that needs ongoing access belongs on SMART on FHIR, where the patient signs in and authorizes your registered app with OAuth, and no secret is copied by hand.

  3. Ask for a synthetic patient to test against

    There is no self-serve sandbox for patient keys yet. If you are building an MCP client and want a synthetic patient record to test with, email info@chartvoyant.com or use the support form. A person reads every request.