Skip to main content

MCP Server Integration Guide

The HealthEx MCP Server implements the Model Context Protocol, enabling AI agents to access patient health records via OAuth 2.0 and JSON-RPC 2.0.

Protocol Overview​

Model Context Protocol (MCP) is a JSON-RPC 2.0 based protocol for AI agents to interact with external data sources through standardized tool interfaces.

Supported AI Platforms:

  • Claude.ai, Claude Desktop, Claude Code (Anthropic)
  • ChatGPT Apps, Connectors (OpenAI)
  • Any OAuth 2.0 compatible AI agent (contact us for whitelisting)

Integration Requirements​

Prerequisites:

  • OAuth 2.0 client implementation with PKCE support
  • JSON-RPC 2.0 client
  • HTTPS endpoint for OAuth redirects
  • Support for long-running OAuth flows (recommended 30+ minutes)

Supported Data Formats:

  • FHIR R4 (Patient, Condition, Observation, Medication, Procedure, etc.)
  • CCDA (C-CDA R2.1)
  • Clinical notes (plain text)

Core Capabilities​

Authentication​

  • OAuth 2.0 Authorization Code Flow with PKCE (RFC 7636)
  • Dynamic client registration (RFC 7591)
  • Refresh token rotation for security
  • JWT-based access tokens
  • Natural language queries
  • Intelligent relevance ranking

Data Access​

  • Per-patient data isolation
  • Full document retrieval
  • FHIR-compliant resource access

Components​

  1. OAuth 2.0 Server - Client registration and token management
  2. MCP Endpoint - JSON-RPC 2.0 interface (/mcp)
  3. Search Service - Natural language search over patient records
  4. Storage - Secure patient document storage

Integration Flow​

1. Register OAuth Client
   ↓
2. Implement OAuth 2.0 + PKCE
   ↓
3. User grants consent (redirects to HealthEx)
   ↓
4. User selects healthcare organizations to share data from
   ↓
5. Receive authorization code
   ↓
6. Exchange code for access token
   ↓
7. Call MCP endpoints with Bearer token

Getting Started​

1. Register Your Client​

POST /oauth/register
Content-Type: application/json

{
  "client_name": "Your AI Agent",
  "redirect_uris": ["https://your-app.com/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"]
}

2. Implement OAuth Flow​

See OAuth Flow for detailed PKCE implementation.

3. Make MCP Requests​

POST /mcp
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "patient medications"
    }
  }
}

Next Steps​