MCP Server

Connecting to the MCP server, the arguments every tool shares, and how tools report errors.

The MCP server exposes four tools at /mcp:

Tool	Returns
`browse_patient`	A directory listing, or a file's content
`read_patient`	A file's content in a chosen format and length
`search_patient`	Paths whose content matches a keyword query
`get_patient_info`	Patient demographics as JSON

Every tool returns a single text content block.

Connect

Use the Model Context Protocol SDK to connect over streamable HTTP (with SSE support in clients/transports). Every call needs a token with the read scope, passed as Authorization: Bearer <token>. The transport is stateless: there is no client-level session to track. Connect an AI Agent shows the client setup end to end.

Shared arguments

Every tool takes these two arguments:

Argument	Type	Required	Description
`patient_id`	string	Yes	The `patientId` you assigned when creating the patient, as in REST routes.
`session_id`	string	No	A session to record the call on. See Record calls on a session.

Paths

browse_patient and read_patient also take a path, relative to the patient: / for the root, /conditions/active for a folder. VFS Paths lists every path the tree can hold.

A path may start with /patient/{id}/, the form search_patient returns. That prefix is dropped, so the patient is always the one patient_id names.

Record calls on a session

With a session_id, the call and its text result are appended to that session as a tool call and its result. The session is created on first use, so a new id must follow the rules for identifiers you assign.

Recording is best effort: an id no session can be created under records nothing, and the tool still returns its result.

Typical agent flow

browse_patient on / to discover what the patient's record holds.
browse_patient deeper into a domain (conditions, medications, labs, timeline).
read_patient on specific files for detailed context.
search_patient when the agent knows a term but not the path.
get_patient_info for demographics.

Errors

A tool never fails the MCP call for a missing patient or path. It answers in its text instead:

A patient_id with no patient, or no ingested data yet, returns a not-ready message naming the ingest routes to call first:

Patient "abc" not found or no data ingested yet. POST to /v1/patients/abc/ingestions/fhir/r4, /v1/patients/abc/ingestions/fhir/r5, or /v1/patients/abc/ingestions/cda/r2 first, then poll the receipt it returns.

get_patient_info wraps the same message in JSON, as { "error": "..." }.

A path that does not exist returns Path not found: {path}.
A search that matches nothing returns No results for "{query}".