Architecture - claude-mcp-platform

Executive Summary

A Model Context Protocol (MCP) platform orchestrator that manages, routes, and monitors requests across multiple MCP servers. It provides a server registry with capability-based discovery, pattern-based request routing with priority rules and round-robin fallback, periodic health checking with automatic server status management, and metrics collection for request counts, latency, and server availability. Built with TypeScript and Bun runtime, with Docker and docker-compose support for production deployment.

Overview

TypeScript

Language

API/Service

Architecture Diagram

Client Request

MCP Platform
Orchestrator Core

Request Router
Route Resolution

Server Registry
Register / Discover

Health Checker
Periodic Monitoring

Metrics Endpoint
Stats / Latency

Direct Match

Pattern Match
Rule-Based Routing

Round-Robin
Fallback Selection

Target MCP Server

Registered MCP Server Pool

Component Breakdown

Component	File	Purpose
Entry Point	`src/index.ts`	HTTP server setup, API endpoint registration, platform initialization
Types	`src/types.ts`	TypeScript interfaces for servers, routes, health status, metrics
Configuration	`src/config.ts`	Environment-based configuration (port, host, intervals, timeouts)
Server Registry	`src/registry.ts`	Register/deregister servers, capability-based lookup and discovery
Request Router	`src/router.ts`	Pattern-based routing with priority rules, direct match, and round-robin fallback
Health Checker	`src/health.ts`	Periodic health checks, status management (healthy/degraded/unhealthy)

Data Flow / Request Flow

Server Registration -- MCP servers register via POST /servers with their URL, capabilities, and metadata. The registry stores them in the active pool.
Health Monitoring -- The health checker polls registered servers at a configurable interval (default 30s). Unhealthy servers are removed from routing.
Request Routing -- Incoming requests to POST /route are resolved via: (1) direct match by server name, (2) pattern match against routing rules with priority, (3) round-robin across healthy servers.
Metrics Collection -- Each routed request increments counters and records latency. GET /metrics exposes request stats, latency percentiles, and server status.
Platform Health -- GET /health returns overall platform status including registered server count, healthy count, and uptime.

Security Controls

Control	Implementation
Health Gating	Unhealthy servers are automatically removed from routing pool
Request Timeout	Configurable request timeout (default 10s) prevents hung connections
Retry Logic	Configurable max retries (default 3) with automatic failover
Network Isolation	Docker network isolation for inter-service communication
Input Validation	Request parameters validated before routing

Industry Adaptation

Healthcare

Route patient data queries to HIPAA-compliant MCP servers. Health monitoring ensures clinical system availability SLAs.

Finance

Priority-based routing for latency-sensitive trading queries. Metrics tracking for SLA compliance and audit trails.

Government

Route classified vs. unclassified requests to appropriate security-cleared MCP server pools. FedRAMP boundary enforcement.

Retail

Round-robin load balancing across regional MCP servers for localized product data. Auto-failover during peak traffic.

SaaS

Multi-tenant routing by capability. Per-tenant metrics and usage tracking. Horizontal scaling of MCP server pools.

Production Readiness Checklist

Configure MCP_PORT, MCP_HOST for production network
Set appropriate MCP_HEALTH_INTERVAL for server monitoring
Configure MCP_REQUEST_TIMEOUT based on expected latencies
Register all MCP servers with correct capabilities
Set up routing rules with appropriate priorities
Deploy via docker-compose for production
Configure reverse proxy (nginx/Caddy) with TLS termination
Set up external monitoring for /health endpoint
Configure log aggregation for request/routing logs
Set up alerting on /metrics for anomalous latency or error rates

Configuration / Environment Variables

Variable	Default	Description
`MCP_PORT`	3000	Server port
`MCP_HOST`	0.0.0.0	Server host
`MCP_LOG_LEVEL`	info	Log level
`MCP_HEALTH_INTERVAL`	30000	Health check interval (ms)
`MCP_REQUEST_TIMEOUT`	10000	Request timeout (ms)
`MCP_MAX_RETRIES`	3	Max retry attempts

Deployment

Using Bun

bun install
bun run dev     # development
bun run start   # production

Using Docker

docker-compose up -d

# Or build manually:
docker build -t claude-mcp-platform .
docker run -p 3000:3000 claude-mcp-platform

Links

Repository	github.com/your-org/claude-mcp-platform
README	README.md
Changelog	CHANGELOG.md
License	MIT License