MCP Registry API
Scalable MCP connection registry with load balancing and health monitoring.
Overview
Service: MCP Registry
Port: 3000
Domain: mcp-registry.local.bluefly.io
Protocol: REST + WebSocket
Version: 0.2.0
OpenAPI Spec: /technical-guide/openapi/agent-protocol/mcp-registry.openapi.yaml
What It Does
Central registry for managing thousands of MCP (Model Context Protocol) connections: - Connection lifecycle management: Register, monitor, deregister MCP servers - Load balancing: Distribute requests across available MCP servers - Health monitoring: Track server health and performance - Capability discovery: Find MCP servers by capability - Batch operations: Manage multiple connections efficiently - Real-time metrics: Monitor registry performance
Architecture
graph TB
A[MCP Clients] --> B[MCP Registry]
B --> C[Connection Pool]
C --> D[MCP Server 1]
C --> E[MCP Server 2]
C --> F[MCP Server N]
B --> G[Health Monitor]
B --> H[Load Balancer]
B --> I[Metrics Store]
Core Endpoints
1. Connection Management
List Connections
GET /connections?status=active&capability=filesystem&protocol=stdio
Query Parameters:
- status (enum: active, idle, disconnected, error)
- type (enum: server, client)
- protocol (enum: stdio, http, websocket)
- capability (string) - Filter by capability
Response:
{
"connections": [
{
"id": "mcp-conn-123",
"name": "filesystem-mcp",
"type": "server",
"protocol": "stdio",
"status": "active",
"capabilities": [
"read_file",
"write_file",
"list_directory"
],
"endpoint": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
},
"health": {
"status": "healthy",
"lastCheck": "2025-01-15T10:00:00Z",
"uptime": 86400,
"errorRate": 0.001
},
"metrics": {
"requestsPerMinute": 45,
"averageLatency": 120,
"activeConnections": 5
}
}
],
"total": 127,
"filtered": 1
}
Register Connection
POST /connections
Request:
{
"name": "gitlab-mcp",
"type": "server",
"protocol": "stdio",
"endpoint": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-gitlab",
"--token",
"${GITLAB_TOKEN}"
]
},
"capabilities": [
"create_issue",
"update_issue",
"list_projects",
"get_file_contents"
],
"metadata": {
"version": "1.0.0",
"owner": "llm-platform",
"environment": "production"
},
"healthCheck": {
"enabled": true,
"interval": 30,
"timeout": 5000
}
}
Response:
{
"id": "mcp-conn-456",
"name": "gitlab-mcp",
"status": "active",
"connection": {
"id": "mcp-conn-456",
"type": "server",
"protocol": "stdio",
"capabilities": ["create_issue", "update_issue", "list_projects", "get_file_contents"],
"health": {
"status": "initializing",
"lastCheck": "2025-01-15T10:05:00Z"
}
},
"createdAt": "2025-01-15T10:05:00Z"
}
Get Connection Details
GET /connections/{connectionId}
Response:
{
"id": "mcp-conn-456",
"name": "gitlab-mcp",
"type": "server",
"protocol": "stdio",
"status": "active",
"capabilities": [
{
"name": "create_issue",
"description": "Create a GitLab issue",
"schema": {
"type": "object",
"properties": {
"project": { "type": "string" },
"title": { "type": "string" },
"description": { "type": "string" }
}
}
}
],
"health": {
"status": "healthy",
"lastCheck": "2025-01-15T10:05:00Z",
"uptime": 300,
"checksPerformed": 10,
"failedChecks": 0
},
"metrics": {
"totalRequests": 523,
"successRate": 0.998,
"averageLatency": 150,
"p95Latency": 300,
"errorRate": 0.002
},
"createdAt": "2025-01-15T10:00:00Z",
"lastActiveAt": "2025-01-15T10:04:55Z"
}
Update Connection
PATCH /connections/{connectionId}
Request:
{
"status": "idle",
"metadata": {
"maintenance": true
},
"healthCheck": {
"interval": 60
}
}
Disconnect Connection
DELETE /connections/{connectionId}
Response:
{
"id": "mcp-conn-456",
"status": "disconnected",
"message": "Connection gracefully terminated",
"disconnectedAt": "2025-01-15T10:10:00Z"
}
2. Capability Discovery
Search by Capability
POST /connections/discover
Request:
{
"capabilities": ["read_file", "write_file"],
"filters": {
"status": "active",
"protocol": "stdio",
"minUptime": 3600
},
"loadBalancing": {
"strategy": "least-loaded",
"maxConnections": 3
}
}
Response:
{
"connections": [
{
"id": "mcp-conn-123",
"name": "filesystem-mcp",
"capabilities": ["read_file", "write_file", "list_directory"],
"health": {
"status": "healthy",
"uptime": 86400
},
"load": 0.23,
"endpoint": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem"]
}
},
{
"id": "mcp-conn-789",
"name": "filesystem-mcp-backup",
"capabilities": ["read_file", "write_file"],
"health": {
"status": "healthy",
"uptime": 43200
},
"load": 0.15,
"endpoint": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem"]
}
}
],
"totalMatching": 2,
"loadBalanced": true,
"strategy": "least-loaded"
}
List All Capabilities
GET /capabilities
Response:
{
"capabilities": [
{
"name": "read_file",
"description": "Read file from filesystem",
"providers": 5,
"totalRequests": 15234,
"averageLatency": 120
},
{
"name": "create_issue",
"description": "Create GitLab issue",
"providers": 2,
"totalRequests": 523,
"averageLatency": 850
}
],
"totalCapabilities": 47
}
3. Health Monitoring
Health Check
POST /connections/{connectionId}/health-check
Response:
{
"connectionId": "mcp-conn-456",
"health": {
"status": "healthy",
"responseTime": 45,
"timestamp": "2025-01-15T10:15:00Z"
},
"diagnostics": {
"processRunning": true,
"memoryUsage": "45MB",
"cpuUsage": 12.5,
"activeRequests": 3
}
}
Batch Health Check
POST /connections/health-check/batch
Request:
{
"connectionIds": ["mcp-conn-123", "mcp-conn-456", "mcp-conn-789"],
"timeout": 5000
}
Response:
{
"results": [
{
"connectionId": "mcp-conn-123",
"status": "healthy",
"responseTime": 45
},
{
"connectionId": "mcp-conn-456",
"status": "healthy",
"responseTime": 52
},
{
"connectionId": "mcp-conn-789",
"status": "error",
"error": "Connection timeout after 5000ms"
}
],
"summary": {
"total": 3,
"healthy": 2,
"unhealthy": 1
}
}
4. Registry Operations
Get Registry Statistics
GET /registry/stats
Response:
{
"timestamp": "2025-01-15T10:20:00Z",
"connections": {
"total": 127,
"active": 115,
"idle": 8,
"disconnected": 3,
"error": 1
},
"protocols": {
"stdio": 87,
"http": 32,
"websocket": 8
},
"capabilities": {
"total": 47,
"mostUsed": [
{ "name": "read_file", "requests": 15234 },
{ "name": "write_file", "requests": 8523 },
{ "name": "create_issue", "requests": 523 }
]
},
"performance": {
"averageLatency": 145,
"requestsPerSecond": 87.5,
"errorRate": 0.012
}
}
Export Configuration
GET /registry/export
Response:
{
"version": "0.2.0",
"exportedAt": "2025-01-15T10:25:00Z",
"connections": [
{
"name": "filesystem-mcp",
"type": "server",
"protocol": "stdio",
"endpoint": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
},
"capabilities": ["read_file", "write_file", "list_directory"]
}
],
"totalExported": 127
}
5. Load Balancing
Get Load Distribution
GET /load-balancing/distribution
Response:
{
"strategy": "least-loaded",
"connections": [
{
"id": "mcp-conn-123",
"name": "filesystem-mcp",
"load": 0.23,
"activeRequests": 5,
"capacity": 20
},
{
"id": "mcp-conn-789",
"name": "filesystem-mcp-backup",
"load": 0.15,
"activeRequests": 3,
"capacity": 20
}
],
"recommendations": [
{
"action": "scale-up",
"reason": "Load exceeding 80% on 2 connections",
"suggestedConnections": 1
}
]
}
Real-time Monitoring
WebSocket Stream
WebSocket: ws://mcp-registry.local.bluefly.io/registry/stream
Subscribe Message:
{
"action": "subscribe",
"events": ["connection-status", "health-check", "capability-request"]
}
Stream Events:
{
"type": "connection-status",
"connectionId": "mcp-conn-456",
"status": "active",
"timestamp": "2025-01-15T10:30:00Z"
}
{
"type": "health-check",
"connectionId": "mcp-conn-456",
"health": "degraded",
"responseTime": 1200,
"timestamp": "2025-01-15T10:30:05Z"
}
Drupal Integration
MCP Registry integrates with Drupal MCP Registry module:
Sync to Drupal:
POST /drupal/sync
Request:
{
"drupalEndpoint": "http://llm.local.bluefly.io",
"apiKey": "${DRUPAL_API_KEY}",
"syncMode": "bidirectional"
}
Health & Metrics
GET /health
Response:
{
"status": "healthy",
"version": "0.2.0",
"uptime": 86400,
"registry": {
"connections": 127,
"healthy": 115,
"unhealthy": 12
},
"performance": {
"requestsPerSecond": 87.5,
"averageLatency": 145
}
}