MCP API Reference

MCP Endpoint

The MCP endpoint implements the Model Context Protocol using JSON-RPC 2.0 over HTTP.

POST /mcp

Authentication

This endpoint requires a patient token obtained via OAuth 2.0 authorization flow.

Request Headers

Header	Value	Required
Authorization	Bearer {access_token}	Yes
Content-Type	application/json	Yes
Accept	application/json or text/event-stream

Accept Header

• Use application/json for standard JSON responses
• Use text/event-stream for Server-Sent Events (SSE) streaming responses

Request Body

The body must be a valid JSON-RPC 2.0 message:

Field	Type	Required	Description
jsonrpc	string	Yes	Must be "2.0"
id	number | string	Yes*	Request identifier (*not required for notifications)
method	string	Yes	The MCP method to call
params	object		Method-specific parameters

---

MCP Methods

Initialize

Establish protocol version and capabilities. Call this first to initialize the session.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "Your Client Name",
      "version": "1.0.0"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "HealthEx MCP Server",
      "version": "1.0.0",
      "description": "MCP server for healthcare data search for patients"
    }
  }
}

---

Notifications/Initialized

Confirm initialization is complete. This is a notification (no response expected).

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

Response: HTTP 202 Accepted (no body)

---

Tools/List

List all available tools.

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

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "get_health_summary",
        "description": "Retrieve a comprehensive current health snapshot",
        "inputSchema": {
          "type": "object",
          "properties": {}
        }
      },
      {
        "name": "search",
        "description": "Search HealthEx data",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "A single query string to search for"
            }
          },
          "required": ["query"]
        }
      }
    ]
  }
}

---

Tools/Call

Execute a tool. This method requires patient consent verification.

Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_health_summary",
    "arguments": {}
  }
}

Response:

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

Consent Required

The tools/call method verifies that the patient has consented to PATIENT_DIRECTED_DATA_EXCHANGE before executing the tool. If consent is not granted, a 403 error is returned.

---

Resources/List

List available resources.

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/list",
  "params": {}
}

---

Request Examples

cURL

Initialize:

curl -X POST "https://api.healthex.io/mcp" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "My App",
        "version": "1.0.0"
      }
    }
  }'

List Tools:

curl -X POST "https://api.healthex.io/mcp" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Call a Tool:

curl -X POST "https://api.healthex.io/mcp" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_health_summary",
      "arguments": {}
    }
  }'

Search:

curl -X POST "https://api.healthex.io/mcp" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": {
        "query": "What are my current medications?"
      }
    }
  }'

---

Error Responses

HTTP Status Codes

Status	Description
200	Success
202	Accepted (for notifications)
401	Unauthorized - invalid or missing token
403	Forbidden - invalid project, patient mismatch, or consent revoked

JSON-RPC Error Codes

Code	Meaning
-32700	Parse error - invalid JSON
-32600	Invalid request - not a valid JSON-RPC request
-32601	Method not found
-32602	Invalid params
-32603	Internal error

Error Response Format

HTTP 401 Unauthorized:

{
  "error": "unauthorized"
}

HTTP 403 Forbidden (consent revoked):

{
  "error": "Data Access is revoked!"
}

HTTP 403 Forbidden (invalid project):

{
  "error": "Invalid Project"
}

JSON-RPC Error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

---

Available Tools

For a complete list of available tools and their parameters, see MCP Server Tools.

Common tools include:

• get_health_summary - Comprehensive health snapshot
• get_conditions - Medical conditions history
• get_medications - Medication details and history
• get_labs - Laboratory test results
• get_vitals - Vital sign measurements
• get_procedures - Medical procedures
• get_immunizations - Vaccination history
• get_visits - Clinical visit history
• search - Natural language search across all records
• search_clinical_notes - Search clinical notes

---

Notes

• The MCP endpoint is stateless - each request is independent
• DNS rebinding protection is enabled
• The isTestPatient flag in the token identifies test patients
• Requests are rate-limited to prevent abuse