practice-fusion-mcp

An open-source, FHIR-first, read-only Model Context Protocol server for Practice Fusion. Connect Claude (Desktop / Code), Cursor, or any MCP client to a Practice Fusion EHR to search patients and providers and review appointments, conditions, medications, labs, vitals, allergies, immunizations, encounters, documents, procedures, diagnostic reports, care plans, and goals — running on Practice Fusion's free Open FHIR account.

Read-only by design. Audit-logged. No write access, no scheduling, no patient creation.

Contents

• Architecture
• Tools
• Prompts & resources
• Example
• Demo mode
• Setup
  • Environment variables
  • MCP clients
  • Troubleshooting
• Security & HIPAA
• How it differs from the alternative
• Development

Architecture

flowchart LR
    C["MCP client<br/>Claude Desktop / Code · Cursor"] -- stdio --> S

    subgraph S["practice-fusion-mcp"]
      direction TB
      T["18 read tools<br/>patients · providers · appointments<br/>conditions · meds · labs · vitals<br/>allergies · immunizations · encounters<br/>documents · coverage · procedures · reports<br/>care plans · goals · everything"]
      A["Audit logger<br/>stderr + optional file<br/>PHI-redacted"]
      F["FHIR client<br/>Bundle unwrap · shapers<br/>pagination · sanitized errors"]
      TP["SMART backend-services<br/>TokenProvider<br/>signed JWT assertion · token cache"]
      T -. audited .-> A
      T --> F
      F --> TP
    end

    TP -- "OAuth2 client-credentials" --> AUTH["PF token endpoint"]
    F -- "read-only FHIR R4" --> PF["Practice Fusion<br/>Open FHIR API"]
    AUTH -- access token --> F

Every tool call flows through the audit logger; the FHIR client only ever holds a short-lived token minted from a signed JWT assertion (SMART backend-services), and long free-text parameters are redacted before anything is logged.

Tools

All tools are namespaced with a practicefusion_ prefix (so they don't collide when loaded alongside other MCP servers), carry a readOnlyHint annotation, and return a typed outputSchema / structuredContent. List tools accept an optional limit (default 50, max 200) and report count and has_more.

Patients & providers

Clinical

Records

Summary

Procedures & care planning

Prompts & resources

Beyond tools, the server exposes the other two MCP primitives.

Prompts — ready-made templates a client can surface:

Resources — readable by URI:

Resource reads are audit-logged like tool calls.

Example

Ask an MCP client a question and it composes the tools:

You: What are Ana Rivera's active medications?

// 1. resolve the patient
practicefusion_search_patients { "name": "Ana Rivera" }
// → { "results": [{ "id": "abc123", "name": "Ana Rivera", "birthDate": "1984-02-11" }], "count": 1, "has_more": false }

// 2. read her medications
practicefusion_get_medications { "patientId": "abc123" }
// → { "results": [
//      { "medication": "Lisinopril 10 mg", "status": "active" },
//      { "medication": "Atorvastatin 20 mg", "status": "active" }
//    ], "count": 2, "has_more": false }

Assistant: Ana Rivera has 2 active medications: Lisinopril 10 mg and Atorvastatin 20 mg.

Because every tool returns structuredContent, the client gets typed objects — not just text — so it can chain calls reliably.

Demo mode

You can run everything above with no Practice Fusion account. Demo mode serves in-memory synthetic fixtures — no credentials, no network, no PHI — and the example query returns exactly what's shown.

One command, nothing to clone:

npx -y practice-fusion-mcp --demo

Or from a clone:

pnpm install
pnpm dev --demo

Or point an MCP client at it with the --demo flag (or set PF_DEMO=1 in its env):

{
  "mcpServers": {
    "practice-fusion-demo": {
      "command": "npx",
      "args": ["-y", "practice-fusion-mcp", "--demo"]
    }
  }
}

The fixtures cover two patients across every resource type — conditions, medications, labs, vitals, allergies, immunizations, appointments, encounters, documents, and coverage — so each tool returns something. It's the quickest way to see the tools before wiring real credentials.

Setup

1. Register a free Practice Fusion Open FHIR developer account and create a System / backend-services app. Note your FHIR base URL, token URL, client id, and register your app's public key.
2. Provide the environment variables below. In production, use your MCP client's env block (shown in step 3). For local development, copy .env.example to .env — pnpm dev loads it automatically.
3. Add to your MCP client config, e.g. Claude Desktop: