How to add FHIR MCP Server to Windsurf

Expose any FHIR server or API as MCP tools to search, read, and write clinical data with SMART-on-FHIR auth. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 124★ · stdio · oauth · official

Windsurf config for FHIR MCP Server

uvx fhir-mcp-server

{
  "mcpServers": {
    "fhir-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/fhir-mcp-server",
        "run",
        "fhir-mcp-server",
        "--transport",
        "stdio"
      ],
      "env": {
        "FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token"
      }
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the FHIR MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5FHIR MCP Server's tools become available to Cascade.

Before you start

Python 3.8+
uv (for dependency management)
An accessible FHIR API server (e.g. HAPI FHIR, Epic sandbox)

What FHIR MCP Server can do in Windsurf

get_capabilities

Retrieves metadata about a specified FHIR resource type, including its supported search parameters and custom operations. Parameter: type (FHIR resource type name, e.g. Patient, Observation, Encounter).

search

Executes a standard FHIR search interaction on a given resource type, returning a bundle or list of matching resources. Parameters: type, searchParam (map of search parameter names to values), and optional response_filter_fhirpaths (array of FHIRPath expressions to filter the response bundle).

read

Performs a FHIR read interaction to retrieve a single resource instance by type and resource ID, optionally refined with search parameters or custom operations (e.g. $everything). Parameters: type, id, searchParam, operation, and optional response_filter_fhirpaths.

create

Executes a FHIR create interaction to persist a new resource of the specified type. Parameters: type, payload (full FHIR resource body), searchParam, and operation (e.g. $evaluate).

update

Performs a FHIR update interaction by replacing an existing resource instance's content with the provided payload. Parameters: type, id, payload, searchParam, and operation (e.g. $lastn).

delete

Executes a FHIR delete interaction on a specific resource instance. Parameters: type, id, searchParam, and operation (e.g. $expand).

get_user

Retrieves the currently authenticated user's FHIR resource (e.g. the linked Patient resource) and returns a concise profile with available demographic fields such as id, name, and birthDate. Requires the fhirUser and openid scopes.

Security

Uses SMART-on-FHIR / OAuth 2.0 authorization code grant by default; configure FHIR_SERVER_CLIENT_ID, FHIR_SERVER_CLIENT_SECRET, and FHIR_SERVER_SCOPES, or set FHIR_SERVER_ACCESS_TOKEN to use a token directly. Set FHIR_SERVER_DISABLE_AUTHORIZATION=True for public FHIR servers. The README notes that when running locally via Docker or Docker Compose, authorization should currently be disabled (FHIR_SERVER_DISABLE_AUTHORIZATION=True) pending a future fix. Handles protected health information (PHI) — secure FHIR credentials and access tokens accordingly.

FHIR MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the FHIR MCP Server config there under the "mcpServers" key and restart the client.

Is FHIR MCP Server safe to use with Windsurf?

Which FHIR servers does it work with?

Any accessible FHIR API server. The README demonstrates a public HAPI FHIR server (no auth flow needed) and the Epic EHR sandbox (full OAuth 2.0 authorization code grant). Set FHIR_SERVER_BASE_URL to the target server.

How is authentication handled?

It uses SMART-on-FHIR / OAuth 2.0 authorization code grant by default (configure FHIR_SERVER_CLIENT_ID, FHIR_SERVER_CLIENT_SECRET, FHIR_SERVER_SCOPES). You can bypass the flow by setting FHIR_SERVER_ACCESS_TOKEN directly, or disable authorization entirely with FHIR_SERVER_DISABLE_AUTHORIZATION=True for public servers.

What transports are supported?

stdio, SSE, and streamable HTTP. The default transport is streamable-http; choose with the --transport CLI flag. By default the server listens on http://localhost:8000.

View repo Full FHIR MCP Server page