FHIRfly
Dashboard

MCP HTTP API Reference

Build custom MCP clients using FHIRfly's HTTP transport endpoints.

Overview

FHIRfly exposes MCP over HTTP with Server-Sent Events (SSE) for streaming responses. This allows any application that implements the MCP specification to connect directly—no Node.js or local server required.

Base URL: https://api.fhirfly.io/mcp

Authentication

All requests require an API key in the header:

x-api-key: ffly_your_api_key_here

Get your API key from Dashboard → Credentials.

Transport Protocol

FHIRfly uses HTTP with SSE (Server-Sent Events) as the transport layer:

  • Requests: Standard HTTP POST with JSON body
  • Responses: SSE stream with JSON-RPC messages

This is the standard MCP HTTP transport defined in the MCP specification.

Endpoints

POST /mcp

The main MCP endpoint. Send JSON-RPC 2.0 requests and receive SSE responses.

Request Headers:

Content-Type: application/json
Accept: text/event-stream
x-api-key: ffly_your_api_key_here

Request Body: JSON-RPC 2.0 message

Response: SSE stream with message events containing JSON-RPC responses

MCP Methods

Initialize Session

Start an MCP session and negotiate capabilities.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-mcp-client",
      "version": "1.0.0"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "fhirfly-mcp-server"
    }
  }
}

List Available Tools

Discover all available FHIRfly tools.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "ndc_get",
        "description": "Look up a drug by its NDC (National Drug Code)",
        "inputSchema": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string",
              "description": "The NDC code to look up (e.g., 0069-0151-01)"
            }
          },
          "required": ["code"]
        }
      },
      {
        "name": "ndc_search",
        "description": "Search drug products by name, ingredient, or dosage form",
        "inputSchema": {
          "type": "object",
          "properties": {
            "q": {
              "type": "string",
              "description": "Search query for drug products"
            },
            "limit": {
              "type": "number",
              "description": "Results per page (1-100, default: 20)"
            }
          }
        }
      }
    ]
  }
}

See MCP Overview for the complete list of 28 available tools.

Call a Tool

Execute a tool with the given arguments.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "ndc_get",
    "arguments": {
      "code": "0069-0151-01"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"ndc\":\"0069-0151-01\",\"brand_name\":\"Lipitor\",\"generic_name\":\"Atorvastatin Calcium\",\"labeler\":\"Pfizer\",\"dosage_form\":\"TABLET, FILM COATED\",\"strength\":\"10 mg\",\"route\":\"ORAL\",\"meta\":{\"source\":\"FDA NDC Directory\"}}"
      }
    ]
  }
}

Example: cURL

List Tools

curl -X POST https://api.fhirfly.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "x-api-key: ffly_your_api_key_here" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call a Tool

curl -X POST https://api.fhirfly.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "x-api-key: ffly_your_api_key_here" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"npi_get",
      "arguments":{"npi":"1234567890"}
    }
  }'

SSE Response Format

Responses are delivered as Server-Sent Events. Each event contains a JSON-RPC message:

event: message
data: {"jsonrpc":"2.0","id":1,"result":{...}}

For tool calls that return large amounts of data, the response may be streamed in chunks:

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"## NDC..."}]}}

Error Handling

Errors follow JSON-RPC 2.0 error format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request"
  }
}

Common Error Codes

Code Message Description
-32700 Parse error Invalid JSON
-32600 Invalid Request Missing required fields
-32601 Method not found Unknown MCP method
-32602 Invalid params Missing or invalid tool arguments
-32603 Internal error Server error

HTTP Status Codes

Status Description
200 Success (check JSON-RPC response for errors)
401 Unauthorized - Invalid or missing API key
429 Rate limited - Too many requests
500 Server error

Building a Custom Client

Here's a minimal example of an MCP client in JavaScript:

async function callMcpTool(toolName, args) {
  const response = await fetch('https://api.fhirfly.io/mcp', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'text/event-stream',
      'x-api-key': process.env.FHIRFLY_API_KEY
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: Date.now(),
      method: 'tools/call',
      params: {
        name: toolName,
        arguments: args
      }
    })
  });

  // Parse SSE response
  const text = await response.text();
  const dataLine = text.split('\n').find(l => l.startsWith('data: '));
  const json = JSON.parse(dataLine.replace('data: ', ''));

  if (json.error) {
    throw new Error(json.error.message);
  }

  return json.result;
}

// Example usage
const result = await callMcpTool('ndc_get', { code: '0069-0151-01' });
console.log(result.content[0].text);

Client Libraries

For production use, we recommend using an existing MCP SDK:

These SDKs handle the SSE parsing, connection management, and error handling for you.

Rate Limits

MCP endpoints share the same rate limits as the REST API. See Rate Limits for details.

Next Steps