FHIRfly
Dashboard

Claude Desktop Setup

Connect FHIRfly to Claude Desktop using MCP.

Prerequisites

  1. Claude Desktop installed (macOS or Windows)
  2. Node.js 18 or later installed
  3. FHIRfly account with an API key

Step 1: Get Your API Key

  1. Go to Dashboard → Credentials
  2. Click Create Credential
  3. Select MCP (AI Assistant)
  4. Name your credential (e.g., "Claude Desktop")
  5. Copy your API key (starts with ffly_)

Step 2: Configure Claude Desktop

Open your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the FHIRfly server:

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

Replace ffly_your_api_key_here with your actual API key.

Step 3: Restart Claude Desktop

Close and reopen Claude Desktop to load the new configuration.

Step 4: Verify Connection

Ask Claude a healthcare question to test the connection:

"What is NDC 0069-0151-01?"

If configured correctly, you'll see a tool indicator and Claude will return detailed drug information from FHIRfly.

Alternative: Global Installation

If you prefer to install the package globally instead of using npx:

npm install -g @fhirfly-io/mcp-server

Then use this configuration:

{
  "mcpServers": {
    "fhirfly": {
      "command": "fhirfly-mcp-server",
      "env": {
        "FHIRFLY_API_KEY": "ffly_your_api_key_here"
      }
    }
  }
}

Alternative: Direct HTTP Connection

If you can't use Node.js, Claude Desktop also supports connecting directly to the FHIRfly API:

{
  "mcpServers": {
    "fhirfly": {
      "url": "https://api.fhirfly.io/mcp",
      "headers": {
        "x-api-key": "ffly_your_api_key_here"
      }
    }
  }
}

This method connects directly to FHIRfly's hosted MCP endpoint without requiring Node.js.

Finding the Config File

macOS

  1. Open Finder
  2. Press Cmd + Shift + G
  3. Paste: ~/Library/Application Support/Claude/
  4. Open or create claude_desktop_config.json

Windows

  1. Press Win + R
  2. Type: %APPDATA%\Claude
  3. Press Enter
  4. Open or create claude_desktop_config.json

Troubleshooting

"Could not connect to MCP server"

  • Verify Node.js is installed: run node --version in your terminal
  • Check your API key is correct and starts with ffly_
  • Make sure the JSON syntax is valid (no trailing commas)

"Tool not available" or No Tools Shown

  • Restart Claude Desktop completely (quit and reopen)
  • Check the MCP server is in your config file
  • Verify your API key has the correct scopes

"Unauthorized" or "Invalid API key"

  • Your API key may be expired or revoked
  • Generate a new credential in the dashboard

"FHIRFLY_API_KEY environment variable is required"

  • Make sure the env section is included in your config
  • Check the API key value is not empty

Debug Mode

To see detailed logs, enable the FHIRFLY_DEBUG environment variable:

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

Logs appear in Claude Desktop's developer console (View → Developer Tools).

Security Notes

  • Your API key is stored locally in your config file
  • The MCP server runs locally on your machine
  • API calls go directly from your machine to FHIRfly
  • Use separate credentials for different machines
  • Rotate credentials if you suspect compromise

Next Steps