Assistant API reference

My Health Passport publishes a Model Context Protocol (MCP) server so assistants, partner apps and internal systems can work with a patient's record through one standard interface. Every call runs as the signed-in patient and only ever touches their own data.

Server my-health-passport-mcp · version 0.2.0 · 13 tools

Endpoint

A single JSON-RPC 2.0 endpoint over HTTP (MCP Streamable HTTP). Requests must accept both JSON and event-stream responses.

POST https://my-health-passport.app/mcp
Content-Type: application/json
Accept: application/json, text/event-stream
Authorization: Bearer <access token>

Authentication

OAuth 2.1 with PKCE and dynamic client registration. Point your client at the endpoint and it will discover the authorization server automatically; the patient signs in and approves the connection. Tokens are issued for that one patient — there is no organisation-wide key that reads everybody, by design.

# discovery (no token needed)
curl -s https://my-health-passport.app/.well-known/oauth-protected-resource/mcp

issuer:    https://jglmdfvmbonyegxiwbyw.supabase.co/auth/v1
audience:  authenticated

Listing the tools

curl -s https://my-health-passport.app/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Response structure

Every tool returns the standard MCP result: a human-readable content block and, for reads, a machine-readable structuredContent object keyed by the tool's subject.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [ { "type": "text", "text": "[ ... JSON ... ]" } ],
    "structuredContent": {
      "medications": [
        {
          "id": "c11a61dc-…",
          "name": "Sinemet",
          "generic_name": "Carbidopa / Levodopa",
          "dosage": "25/100 mg",
          "form": "tablet",
          "instructions": "Take 1 tablet 3 times daily, 30 min before meals.",
          "prescriber": "Dr. Patel (Neurology)",
          "active": true
        }
      ]
    }
  }
}

Errors come back as a result with isError: true and a plain-text reason (expired consent, unknown record, missing permission). Unauthenticated requests get HTTP 401 with the OAuth discovery header.

Read tools

list_medications

read

List the signed-in patient's medications from My Health Passport. Returns name, dose, instructions, and active status.

Parameters

Name	Type	Required	Description
include_inactive	boolean	no	Include medications marked inactive. Defaults to false.

Example call

curl -s https://my-health-passport.app/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_medications", "arguments": { "include_inactive": true } } }'

list_allergies

read

List the signed-in patient's recorded allergies and reactions.

Parameters

None.

Example call

curl -s https://my-health-passport.app/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_allergies", "arguments": {} } }'

list_conditions

read

List the signed-in patient's recorded health conditions or diagnoses, with status, severity and diagnosis date.

Parameters

None.

Example call

curl -s https://my-health-passport.app/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_conditions", "arguments": {} } }'

list_immunizations

read

List the signed-in patient's vaccinations, including dose number, date given and when the next dose is due.

Parameters

None.

Example call

curl -s https://my-health-passport.app/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_immunizations", "arguments": {} } }'

list_todays_doses

read

List the signed-in patient's scheduled doses for today with their taken/missed status.

Parameters

None.

Example call

curl -s https://my-health-passport.app/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_todays_doses", "arguments": {} } }'

adherence_summary

read

Summarise how well the signed-in patient has kept to their medication schedule over a recent period: doses taken, missed, skipped and the adherence rate.

Parameters

Name	Type	Required	Description
days	integer	no	How many days back to summarise. Defaults to 30.

Example call

curl -s https://my-health-passport.app/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "adherence_summary", "arguments": { "days": 7 } } }'

list_refills_due

read

List the signed-in patient's prescription refills that are due soon or still in progress, with pharmacy and status.

Parameters

Name	Type	Required	Description
within_days	integer	no	Only include refills due within this many days. Defaults to 30.

Example call

curl -s https://my-health-passport.app/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_refills_due", "arguments": { "within_days": 7 } } }'

list_recent_alerts

read

List recent open medication alerts for the signed-in patient — recalls, interaction conflicts, and safety warnings.

Parameters

Name	Type	Required	Description
limit	integer	no	Max alerts to return (default 20).

Example call

curl -s https://my-health-passport.app/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_recent_alerts", "arguments": { "limit": 7 } } }'

list_connections

read

List the people connected to the signed-in patient (care partners, family, clinicians, emergency contacts) and any invitations that are still pending.

Parameters

None.

Example call

curl -s https://my-health-passport.app/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_connections", "arguments": {} } }'

Action tools

These change the patient's record. Confirm with the patient before calling them.

log_dose

writes data

Mark a scheduled dose for the signed-in patient as taken or skipped. Give either the dose id from list_todays_doses or the medication name; the nearest pending dose today is used.

Parameters

Name	Type	Required	Description
dose_id	string	no	Dose id from list_todays_doses.
medication	string	no	Medication name, when no dose id is known.
status	"taken" \| "skipped"	no	Whether the dose was taken or skipped. Defaults to taken.
note	string	no	Optional reason for skipping.

Example call

curl -s https://my-health-passport.app/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "log_dose", "arguments": { "dose_id": "example", "medication": "example", "status": "taken", "note": "example" } } }'

record_symptom

writes data

Record a symptom or side effect the signed-in patient noticed, optionally linked to a medication, so it appears in their passport and side-effect history.

Parameters

Name	Type	Required	Description
description	string	yes	What the patient felt, in their own words.
medication	string	no	Medication this may relate to, by name.
severity	integer	no	Severity from 1 (mild) to 10 (severe).
symptoms	array	no	Short symptom labels, e.g. nausea, dizziness.

Example call

curl -s https://my-health-passport.app/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "record_symptom", "arguments": { "description": "example", "medication": "example", "severity": 7, "symptoms": [ "example" ] } } }'

share_medication_schedule

writes data

Create a time-limited link that lets someone view the signed-in patient's medication schedule. Returns the link; it is not sent anywhere automatically.

Parameters

Name	Type	Required	Description
recipient	string	no	Who the link is for, used only as a label.
expires_in_days	integer	no	How long the link stays valid. Defaults to 7 days.

Example call

curl -s https://my-health-passport.app/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "share_medication_schedule", "arguments": { "recipient": "example", "expires_in_days": 7 } } }'

invite_connection

writes data

Create an invitation for someone to connect to the signed-in patient at a chosen level (care partner, family, clinician or emergency contact). Returns the invite link and short code to pass on.

Parameters

Name	Type	Required	Description
name	string	yes	The person's name.
level	"care_partner" \| "family" \| "clinician" \| "emergency_contact"	yes	Connection level to grant.
email	string	no	Their email, if known.
phone	string	no	Their mobile number, if known.
expires_in_days	integer	no	How long the invitation stays valid. Defaults to 14 days.

Example call

curl -s https://my-health-passport.app/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "invite_connection", "arguments": { "name": "example", "level": "care_partner", "email": "example", "phone": "example", "expires_in_days": 7 } } }'

Deliberately not available

Emergency/SOS dispatch, admin and compliance functions, payer and network queues, bulk export, and anything that reads a person other than the signed-in patient. Partner organisations that need consented access to several patients use the partner portal and its per-patient keys instead.