Add the FHIRfly MCP Server to Claude, Cursor & Windsurf

You've decided to give your AI assistant real medical codes instead of hallucinated ones. This is the exact setup — the config each MCP client expects, how to confirm the tools loaded, and what to check when they don't.

The FHIRfly MCP server is a thin stdio bridge. It runs locally via npx, forwards tools/list and tools/call to the FHIRfly API, and exposes 50+ healthcare reference tools — providers, drugs, diagnoses, labs, and claims codes across 21+ systems. Any MCP-compatible client can drive it. The config shape is nearly identical across most clients — only the file path and the way you register it differ (VS Code is the one exception, with its own schema, covered below).

Prerequisites

• Node.js 18+ on your machine (node --version to check). The server is fetched on demand with npx — there is nothing to install globally.
• A FHIRfly API key. The free tier is 10,000 requests/month across all data types, no credit card.

Step 1: Create an MCP API key

From the dashboard, click Create Credential and select MCP. Copy the key — it starts with ffly_live_. You'll paste it into the env block below as FHIRFLY_API_KEY.

Every client uses the same server invocation. Here is the canonical block; the sections below show where each client wants it:

{
  "mcpServers": {
    "fhirfly": {
      "command": "npx",
      "args": ["-y", "@fhirfly-io/mcp-server"],
      "env": { "FHIRFLY_API_KEY": "ffly_live_your_key_here" }
    }
  }
}

Step 2: Register the server in your client

Claude Desktop

Edit the config file for your OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Paste the canonical block, save, then completely quit and reopen Claude Desktop (a window close is not enough). The FHIRfly tools appear under the tools menu once it restarts.

Cursor

Cursor reads MCP config from ~/.cursor/mcp.json for all projects, or .cursor/mcp.json inside a project for a scoped setup. The schema is the same mcpServers block above. After saving, open Settings → MCP and confirm fhirfly shows a green status.

Windsurf

Windsurf stores its config at ~/.codeium/windsurf/mcp_config.json, using the same mcpServers shape. Save the file, then hit the refresh control in the Windsurf MCP panel — no full restart required.

VS Code

VS Code (Copilot agent mode) is the exception to the shared shape. It reads .vscode/mcp.json with a top-level servers key — not mcpServers — and prefers an inputs prompt over a hardcoded key, so the secret never lands in the file:

{
  "servers": {
    "fhirfly": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fhirfly-io/mcp-server"],
      "env": { "FHIRFLY_API_KEY": "${input:fhirfly-key}" }
    }
  },
  "inputs": [
    {
      "id": "fhirfly-key",
      "type": "promptString",
      "description": "FHIRfly API key",
      "password": true
    }
  ]
}

VS Code prompts for the key the first time the server starts and stores it in its secret store. Start the server from the Start action shown inline in the config file.

Claude Code

Skip the JSON file entirely and register it from the CLI:

claude mcp add fhirfly \
  -e FHIRFLY_API_KEY=ffly_live_your_key_here \
  -- npx -y @fhirfly-io/mcp-server

Run claude mcp list to confirm fhirfly is connected. To share the server with a repo, commit a project-scoped .mcp.json with the same block instead.

Step 3: Verify the connection

Ask the assistant something that can only be answered by a live tool call, using a known NPI:

What is the provider name and specialty for NPI 1679576722?

If the setup is correct, the model calls npi_get and returns a resolved name and taxonomy — not a guess. You can watch the tool fire in the client's tool-call log. A model that answers without a tool call, or refuses, hasn't loaded the server yet — see below.

Troubleshooting

Set FHIRFLY_DEBUG=1 in the env block to log the JSON-RPC exchange to stderr when you need to see exactly what the bridge is sending.

What you can ask once it's connected

The model now has direct, citable tools instead of memorized codes:

• "Look up NDC 0069-0151-01 and tell me the active ingredient" → ndc_get
• "Search ICD-10 for type 2 diabetes without complications" → icd10_search
• "Are there interactions between these two RxNorm drugs?" → check_drug_interactions
• "What LOINC code corresponds to a hemoglobin A1c measurement?" → loinc_get / loinc_search
• "Find providers named 'hospice' in Oregon" → npi_search

Each answer is grounded in a source lookup, so the model can cite the code system rather than inventing a plausible-looking value.

Key Takeaways

• The FHIRfly MCP server is a local stdio bridge run via npx — nothing to install, one FHIRFLY_API_KEY to set.
• Claude Desktop, Cursor, and Windsurf share the same mcpServers JSON; only the config path differs. Claude Code registers from the CLI with claude mcp add, and VS Code uses its own servers + inputs schema.
• Verify with a known NPI and watch for an actual tool call before trusting the wiring.
• Most setup failures are a stale client cache or a key in the wrong place — a full restart and an env-block check resolve the majority.

Further Reading

• FHIRfly MCP server overview
• The Healthcare Data API for AI Agents: NPI, Drugs, Codes as Tools
• Pricing and free tier
• Try a provider lookup with no signup