MCP Tools

The MCP server exposes four tools at /mcp.

Use the Model Context Protocol SDK to connect over streamable HTTP (with SSE support in clients/transports).

These tools are text-returning MCP tools designed for AI agents:

• browse_patient
• read_patient
• search_patient
• get_patient_info

Important patient ID semantics

Two ID styles appear in MCP calls:

• Path-based tools (browse_patient, read_patient) use VFS paths such as /patient/{id}/....
• Explicit ID tools (search_patient, get_patient_info) take patientId as input.

In both cases, the ID is the VFS patient ID, which is the patient.id extracted from the ingested record (the FHIR Patient.id, or the CDA recordTarget patient ID). This is distinct from the registry key used in REST ingest routes (/patients/{registryKey}/...). The two can differ.

The VFS patient ID is returned in every ingest response as patient.id. To look it up, call GET /patients/{registryKey} and read patient.id from the response.

If no ingested data exists for that patient ID, tools return a not-ready message indicating ingest endpoints to call first.

browse_patient

Navigate a patient's virtual file tree. Returns directory listings or file previews.

Input:
  path: string   (VFS path, e.g. "/patient/{id}/conditions/active")

Output:
  Text result:
  - Directory listing (for directories)
  - File preview/content (for leaf paths)

Usage pattern:

→ browse_patient("/patient/abc/")
← conditions/ medications/ allergies/ labs/ timeline/ family_history/ sources/

→ browse_patient("/patient/abc/conditions/active")
← type_2_diabetes_mellitus/  active since 2016
   hypertension/              active since 2019
   chronic_kidney_disease/    stage 3b, active

→ browse_patient("/patient/abc/conditions/active/type_2_diabetes_mellitus/")
← _story.md   longitudinal condition narrative
   _raw.json   structured entity + relationships

Start with /patient/{id}/ to discover top-level structure, then drill down.

read_patient

Read content from a specific VFS path.

Input:
  path: string              (VFS file path)
  format?: "narrative" | "structured" | "compact"
                            (default: "narrative")
  token_budget?: number     (approximate token budget, 1 token ≈ 4 chars)

Output:
  Text content for the target path in the requested format.

Format guide:

Examples:

read_patient("/patient/abc/conditions/active/type_2_diabetes_mellitus/_story.md")
→ Full condition narrative (Markdown)

read_patient("/patient/abc/medications/current/metformin_1000mg", format="structured")
→ { id, display, codes, dosageText, status, provenance, ... }

read_patient("/patient/abc/labs/latest", format="compact")
→ HbA1c 7.1% (2023-09-07) | eGFR 52 mL/min (2023-08-15) | ...

Use compact when scanning many items. Use token_budget to keep single reads from consuming too much context.

search_patient

Full-text search across all indexed patient data (entities, events, documents, narratives).

Input:
  patientId: string   (VFS patient ID, the id in /patient/{id}/...)
  query: string       (search terms)

Output:
  Text list of matching paths with previews.
  If no matches: `No results for "{query}".`

Example:

search_patient("abc", "metformin")
→ /patient/abc/medications/current/metformin_1000mg
     Metformin 1000mg BID (active)
  /patient/abc/conditions/active/type_2_diabetes_mellitus/_story.md
     ...metformin is the primary medication for this condition...

Search uses BM25 scoring over a pre-built index. It searches display names, codes, attribute text, and narrative section content.

get_patient_info

Returns patient demographics and pipeline statistics as JSON.

Input:
  patientId: string

Output:
  JSON string with patient metadata and load stats:

  {
    id: string,
    name: string,
    birthDate?: string,
    gender?: string,
    stats: {
      entities: number,
      events: number,
      relationships: number,
      warnings: number,
      loadMs: number
    }
  }

Typical agent flow

1. browse_patient on /patient/{id}/ to discover structure.
2. browse_patient deeper into a domain (conditions, medications, labs, timeline).
3. read_patient on specific leaf paths for detailed context.
4. search_patient when the agent knows a term but not the path.
5. get_patient_info for demographics and ingestion stats.

Error behavior

• If patient data is unavailable, tools return a not-ready message indicating the patient was not found or not ingested yet.
• search_patient returns a no-results message when nothing matches.
• get_patient_info returns a JSON error payload when data is unavailable.