Architecture

Local Deployment (stdio)

In the default stdio mode, Claude Desktop or Claude Code spawns MCP servers as child processes. Communication happens via stdin/stdout pipes.

flowchart LR
    subgraph Client["Claude Desktop / Claude Code"]
        A[AI Assistant]
    end

    subgraph Local["Local Processes"]
        B[snomed-mcp]
        C[rxnorm-mcp]
        D[icd10-mcp]
        E[Other MCP Servers]
    end

    A <-->|stdio| B
    A <-->|stdio| C
    A <-->|stdio| D
    A <-->|stdio| E

    B --> F[(Snowstorm API)]
    C --> G[(RxNorm API)]
    D --> H[(ClinicalTables API)]

Characteristics:

• Each server runs as a separate process
• Communication via stdin/stdout (JSON-RPC)
• No network configuration required
• Servers start/stop with the client

Remote HTTP Deployment

In HTTP mode, servers run as standalone services accessible over the network. Multiple clients can connect to shared server instances.

flowchart TB
    subgraph Clients["Clients"]
        C1[Claude Desktop]
        C2[Claude Code]
        C3[Custom Client]
    end

    subgraph Gateway["API Gateway / Load Balancer"]
        LB[nginx / ALB]
    end

    subgraph Services["MCP Services"]
        S1[snomed-mcp :8080]
        S2[rxnorm-mcp :8081]
        S3[icd10-mcp :8082]
        S4[Other Servers]
    end

    subgraph External["External APIs"]
        E1[(Snowstorm)]
        E2[(RxNorm)]
        E3[(ClinicalTables)]
    end

    C1 -->|HTTPS| LB
    C2 -->|HTTPS| LB
    C3 -->|HTTPS| LB

    LB -->|/snomed| S1
    LB -->|/rxnorm| S2
    LB -->|/icd10| S3
    LB --> S4

    S1 --> E1
    S2 --> E2
    S3 --> E3

Characteristics:

• Servers run as long-lived HTTP services
• TLS encryption for secure communication
• API key authentication
• Horizontal scaling with load balancer
• Shared infrastructure across teams

Kubernetes Deployment

Production deployment on Kubernetes with ingress routing, horizontal pod autoscaling, and observability.

flowchart TB
    subgraph Internet
        U[Users / Clients]
    end

    subgraph K8s["Kubernetes Cluster"]
        subgraph Ingress["Ingress Layer"]
            ING[Ingress Controller]
        end

        subgraph NS["clinical-terminology namespace"]
            subgraph Deployments
                D1[snomed-mcp
Deployment]
                D2[rxnorm-mcp
Deployment]
                D3[icd10-mcp
Deployment]
            end

            subgraph Services
                SVC1[snomed-mcp
Service]
                SVC2[rxnorm-mcp
Service]
                SVC3[icd10-mcp
Service]
            end

            CM[ConfigMap]
            SEC[Secrets]
        end

        subgraph Monitoring["Observability"]
            OTEL[OTel Collector]
            PROM[Prometheus]
        end
    end

    U -->|HTTPS| ING
    ING -->|/snomed| SVC1
    ING -->|/rxnorm| SVC2
    ING -->|/icd10| SVC3

    SVC1 --> D1
    SVC2 --> D2
    SVC3 --> D3

    D1 -.-> CM
    D1 -.-> SEC
    D1 -->|metrics| OTEL
    OTEL --> PROM

Components:

• Ingress Controller: Routes traffic by path prefix
• Services: ClusterIP services for internal routing
• Deployments: Pod templates with health probes
• ConfigMap: Shared configuration (log level, timeouts)
• Secrets: API keys and credentials
• OTel Collector: Metrics and traces aggregation

Request Flow

Detailed flow of an MCP request through the HTTP transport layer.

sequenceDiagram
    participant C as Client
    participant M as Middleware Stack
    participant H as MCP Handler
    participant T as Tool
    participant API as External API

    C->>M: POST /mcp (initialize)
    M->>M: Recovery → RequestID → OTel → Logging
    M->>M: CORS → Origin → Auth → RateLimit
    M->>H: Forward request
    H->>H: Create session
    H-->>C: 200 OK + Mcp-Session-Id

    C->>M: POST /mcp (tools/call)
    M->>M: Validate session
    M->>H: Forward request
    H->>T: Execute tool
    T->>API: API request
    API-->>T: Response
    T-->>H: Tool result
    H-->>C: 200 OK (JSON or SSE)

Middleware Order (outside → inside):

1. Recovery: Catch panics, return 500
2. RequestID: Generate/propagate trace ID
3. OTel: Metrics and tracing
4. Logging: Structured request logs
5. CORS: Handle preflight requests
6. Origin: Validate Origin header
7. Auth: API key verification
8. RateLimit: Per-IP rate limiting
9. BodyLimit: Request size limits

Component Dependencies

flowchart TB
    subgraph pkg["pkg/ (shared)"]
        T[transport]
        C[credutil]
        H[httputil]
        M[mcputil]
    end

    subgraph servers["MCP Servers"]
        S1[snomed-mcp]
        S2[rxnorm-mcp]
        S3[icd10-mcp]
        S4[icd11-mcp]
        S5[loinc-mcp]
        S6[umls-mcp]
        S7[ucum-mcp]
    end

    S1 --> T
    S1 --> M
    S2 --> T
    S2 --> M
    S3 --> T
    S3 --> M
    S4 --> T
    S4 --> C
    S5 --> T
    S5 --> C
    S6 --> T
    S6 --> C
    S7 --> T

    T --> H

Shared Packages:

• transport: HTTP server, middleware, health checks, OTel
• credutil: Credential loading (env vars + keyring)
• httputil: HTTP client utilities
• mcputil: MCP server helpers