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

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.

Tool	What it does
practicefusion_search_patients	Find patients by name / birthdate / gender / identifier
practicefusion_get_patient	One patient's demographics by id
practicefusion_get_appointments	Appointments by patient / status / date
practicefusion_get_conditions	A patient's problems / diagnoses
practicefusion_get_medications	A patient's medication requests
practicefusion_get_lab_results	A patient's laboratory observations

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

Var	Required	Default	Notes
PF_FHIR_BASE_URL	yes	—	FHIR R4 base URL
PF_TOKEN_URL	yes	—	OAuth2 token endpoint
PF_CLIENT_ID	yes	—	Backend-services client id
PF_PRIVATE_KEY	yes	—	PKCS8 PEM private key (matches the registered public key)
PF_SCOPES	no	system/*.read	Requested scopes
PF_TOKEN_ALG	no	RS384	JWT signing alg
PF_AUDIT_LOG	no	—	Optional file path for audit records (always also written to stderr)

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/