Server Registry & Discovery

A server registry is the central inventory of every MCP server in your fleet. Each entry records: the server's name and description, its transport type (stdio, Streamable HTTP), its endpoint or command, its current version, its health status, the tools and resources it exposes, and its authentication requirements. The registry serves two audiences: operators who need to know what is deployed and where, and clients who need to discover available servers programmatically. Without a registry, server discovery is tribal knowledge — it lives in someone's head, a wiki page that is three versions out of date, or scattered across configuration files.

Dynamic service discovery integrates the registry with the deployment pipeline. When a new MCP server is deployed, it registers itself by calling the registry API with its metadata. When it shuts down, it deregisters. Health checks periodically verify that registered servers are still responsive and update their status. Clients query the registry to discover servers matching their needs — "find all servers that expose a search_codebase tool" or "find the filesystem server closest to my region." This enables automatic server selection without hardcoded endpoints in client configuration.

Version tracking in the registry is critical for coordinated upgrades. The registry knows which version of each server is running on each instance. A dashboard shows the fleet's version distribution: 80% of instances on v2.3.1, 15% on v2.3.0 (canary rollback), 5% on v2.2.9 (long-lived sessions). This visibility prevents the "what version is production running?" question that wastes 30 minutes during every incident. The registry should reject registrations from versions that have been explicitly deprecated — forcing operators to upgrade rather than running known-bad versions.

// MCP Server Registry entry schema
interface McpServerRegistration {
  // Identity
  id: string;                    // unique server ID
  name: string;                  // human-readable name
  description: string;           // what this server does

  // Transport
  transport: "stdio" | "streamable-http" | "websocket";
  endpoint?: string;             // URL for HTTP/WS transports
  command?: string;              // command for stdio transport

  // Version & health
  version: string;               // semver
  status: "healthy" | "degraded" | "unhealthy" | "draining";
  lastHealthCheck: string;       // ISO timestamp

  // Capabilities (from initialize response)
  capabilities: {
    tools: string[];             // tool names
    resources: string[];         // resource URI patterns
    prompts: string[];           // prompt names
  };

  // Auth requirements
  auth: {
    type: "none" | "oauth2" | "mtls" | "api-key";
    authorizationEndpoint?: string;
    scopes?: string[];
  };

  // Operational metadata
  region: string;                // deployment region
  instanceCount: number;         // current running instances
  registeredAt: string;          // ISO timestamp
}