Clinical Terminology MCP

HTTP API Reference

Complete reference for the Streamable HTTP MCP protocol endpoints.

Overview

When running in HTTP mode (MCP_TRANSPORT=http), servers expose a Streamable HTTP API implementing the Model Context Protocol (MCP).

Endpoints

EndpointMethodDescription
/mcpPOSTMCP JSON-RPC endpoint
/mcpDELETETerminate session
/healthGETCombined health check
/health/liveGETLiveness probe
/health/readyGETReadiness probe

Headers

Required Headers

HeaderValueDescription
Content-Typeapplication/jsonRequest body format
Acceptapplication/json, text/event-streamResponse formats
MCP-Protocol-Version2025-03-26MCP protocol version

Optional Headers

HeaderDescription
Mcp-Session-IdSession ID (returned after initialize)
AuthorizationBearer <api-key> for authenticated servers
X-API-KeyAlternative API key header
X-Request-IDRequest correlation ID (auto-generated if not provided)

MCP Protocol Flow

1. Initialize Session

POST /mcp HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-03-26

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Mcp-Session-Id: abc123-def456-789

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "snomed-mcp",
      "version": "1.0.0"
    }
  }
}

2. List Available Tools

POST /mcp HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-03-26
Mcp-Session-Id: abc123-def456-789

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

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "snomed_search",
        "description": "Search for SNOMED CT concepts by term",
        "inputSchema": {
          "type": "object",
          "properties": {
            "term": {
              "type": "string",
              "description": "Search term"
            },
            "limit": {
              "type": "number",
              "description": "Maximum results (default: 20)"
            }
          },
          "required": ["term"]
        }
      }
    ]
  }
}

3. Call a Tool

POST /mcp HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-03-26
Mcp-Session-Id: abc123-def456-789

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "snomed_search",
    "arguments": {
      "term": "diabetes mellitus",
      "limit": 5
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 5 concepts:\n\n1. Diabetes mellitus (73211009)\n..."
      }
    ]
  }
}

4. Terminate Session

DELETE /mcp HTTP/1.1
Host: localhost:8080
Mcp-Session-Id: abc123-def456-789

Response:

HTTP/1.1 204 No Content

Server-Sent Events (SSE)

For streaming responses, the server may return text/event-stream:

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

data: {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Processing..."}]}}

data: {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Complete result here"}]}}

SSE events are separated by blank lines. Each data: line contains a complete JSON-RPC response.

Health Endpoints

Combined Health Check

GET /health HTTP/1.1
Host: localhost:8080

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"ok"}

Liveness Probe

Returns 200 if the process is running.

GET /health/live HTTP/1.1
Host: localhost:8080

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"ok"}

Readiness Probe

Returns 200 if ready to accept requests, 503 if not ready.

GET /health/ready HTTP/1.1
Host: localhost:8080

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"ok","checks":{"database":"ok"}}

Error Responses

HTTP Errors

StatusDescription
400Bad Request - Invalid JSON or missing required fields
401Unauthorized - Missing or invalid API key
403Forbidden - Origin not allowed
404Not Found - Invalid endpoint
413Payload Too Large - Request body exceeds limit
429Too Many Requests - Rate limit exceeded
500Internal Server Error
503Service Unavailable - Server not ready

JSON-RPC Errors

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": "missing required field: term"
  }
}
CodeMeaning
-32700Parse error - Invalid JSON
-32600Invalid Request - Malformed request
-32601Method not found - Unknown method
-32602Invalid params - Wrong parameters
-32603Internal error - Server error

Authentication

Bearer Token

Authorization: Bearer your-api-key-here

X-API-Key Header

X-API-Key: your-api-key-here

Both methods are supported. Bearer token takes precedence if both are provided.

Unauthenticated Endpoints

Health endpoints (/health, /health/live, /health/ready) do not require authentication.

Rate Limiting

When rate limited, the server returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{"error":"rate limit exceeded","retry_after":60}

Default limit: 100 requests per minute per IP.

CORS

The server includes CORS headers for browser-based clients:

Access-Control-Allow-Origin: https://claude.ai
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Accept, Authorization, X-API-Key, Mcp-Session-Id, MCP-Protocol-Version
Access-Control-Expose-Headers: Mcp-Session-Id
Access-Control-Max-Age: 86400

Preflight requests (OPTIONS) are handled automatically.

Example: curl Session

# Initialize
curl -s -D - -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-03-26" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}' \
  | tee response.txt

# Extract session ID
SESSION_ID=$(grep -i "Mcp-Session-Id:" response.txt | cut -d' ' -f2 | tr -d '\r')

# Call tool
curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-03-26" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"snomed_search","arguments":{"term":"hypertension"}}}'