MCP Registry API

Separation of Duties: See Separation of Duties - API documentation is responsible for documenting APIs. It does NOT own agent manifests, execution, or infrastructure configuration.

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": "0.4.9",
    "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.4.9",
  "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.4.9",
  "uptime": 86400,
  "registry": {
    "connections": 127,
    "healthy": 115,
    "unhealthy": 12
  },
  "performance": {
    "requestsPerSecond": 87.5,
    "averageLatency": 145
  }
}

Next Steps

• Agent Mesh API
• Workflow Engine API
• JWT Authentication