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 review appointments, conditions, medications, and labs — running on Practice Fusion's free Open FHIR account.

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

Architecture

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

    subgraph S["practice-fusion-mcp"]
      direction TB
      T["MCP tools<br/>search_patients · get_patient<br/>appointments · conditions<br/>medications · lab_results"]
      A["Audit logger<br/>stderr + optional file<br/>PHI-redacted"]
      F["FHIR client<br/>Bundle unwrap · shapers<br/>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

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:

{
  "mcpServers": {
    "practice-fusion": {
      "command": "npx",
      "args": ["-y", "practice-fusion-mcp"],
      "env": {
        "PF_FHIR_BASE_URL": "https://fhir.practicefusion.com/r4",
        "PF_TOKEN_URL": "https://auth.practicefusion.com/token",
        "PF_CLIENT_ID": "your-client-id",
        "PF_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
      }
    }
  }
}

Environment variables

Security & HIPAA

This server handles Protected Health Information. You, the deployer, are the covered entity or business associate: you are responsible for your own Business Associate Agreement (BAA) with Veradigm/Practice Fusion and for running this in a HIPAA-appropriate environment. Every tool call is audit-logged (stderr, plus optional file) with long free-text parameters redacted. Tokens and keys are never logged. This project ships code, not a hosted data service. Not legal advice.

How it differs from the alternative

The other Practice Fusion MCP is built on Practice Fusion's proprietary Unity APIs (paid Integrator tier) and is write-heavy. This one is FHIR-based (runs on the free Open account), read-only (smaller risk surface), and audit-logged.

Development

pnpm install
pnpm test        # unit tests (mocked FHIR)
pnpm build       # bundle to dist/