metamcp

Dynamically aggregates tools from multiple MCP servers into isolated namespaces, applying server-to-namespace-to-endpoint three-tier configuration abstraction. Uses a session pool management system that pre-allocates persistent connections to backend MCP servers, eliminating cold-start latency on each client request. The aggregation engine maintains a tool registry synchronized via discovery mechanisms, enabling administrators to selectively expose, override, or filter tools per namespace without modifying upstream servers.

Applies a composable middleware stack to tool definitions and invocations at the namespace level, enabling schema modification, parameter validation, access control filtering, and request/response transformation without modifying upstream MCP servers. Middleware executes in sequence during tool discovery (for schema transformation) and at invocation time (for request/response interception). The system supports both built-in middleware (filtering, renaming, schema override) and custom middleware via plugin interfaces.

Supports chaining MetaMCP instances (MetaMCP connecting to another MetaMCP as an MCP server), enabling hierarchical tool aggregation and delegation. When a MetaMCP instance connects to another MetaMCP, it discovers tools from the downstream instance and can aggregate them into its own namespaces. Tool names are parsed to disambiguate which MetaMCP instance a tool belongs to, enabling multi-level tool hierarchies.

Implements comprehensive error handling for MCP server failures, network issues, and invalid tool invocations. When an MCP server becomes unreachable, the session pool detects the failure via health checks and automatically reconnects. Tool invocation errors are caught, logged, and returned to clients with detailed error messages. The system distinguishes between transient errors (network timeouts, temporary unavailability) and permanent errors (invalid tool, authentication failure), applying appropriate recovery strategies.

Implements backend business logic via tRPC procedures, providing end-to-end type safety from frontend UI to database. tRPC procedures handle configuration mutations (create/update/delete MCP servers, namespaces, endpoints), tool discovery, and session management. Type definitions are shared between frontend and backend, eliminating type mismatches and enabling IDE autocomplete for API calls.

Uses Drizzle ORM to define database schema and implement repository layer for all data persistence (MCP server configurations, namespaces, endpoints, tool registry, API keys, audit logs). Drizzle provides type-safe SQL queries with compile-time validation, migrations for schema evolution, and query builders for complex queries. All data is persisted in PostgreSQL, enabling multi-instance deployments with shared state.

Exposes aggregated MCP servers as public endpoints via three simultaneous transport protocols: Server-Sent Events (SSE) for streaming, Streamable HTTP for request-response, and OpenAPI for REST clients. Each endpoint is independently configurable with its own authentication scheme (API key, OAuth, public), namespace binding, and session lifecycle. The system maintains separate session pools per endpoint, allowing different clients to connect via their preferred protocol without interference.

Implements a multi-tenant authentication and authorization layer supporting both API key and OAuth flows, with per-endpoint and per-namespace access control. API keys are stored in PostgreSQL with scoping rules (allowed endpoints, namespaces, tools), and OAuth integrates with external providers via standard OIDC/OAuth2 flows. The system enforces access control at the endpoint level (which clients can connect) and tool level (which tools a client can invoke), with audit logging of all authenticated requests.

Automatically discovers tools from connected MCP servers via the MCP list_tools protocol, persists tool definitions in PostgreSQL, and maintains a synchronized registry that updates when upstream servers change. Discovery runs on-demand or on a schedule, comparing upstream tool lists against the persisted registry to detect additions, removals, and schema changes. Tool metadata (name, description, input schema, output schema) is stored with namespace-specific overrides applied at query time, enabling tool customization without modifying the canonical definition.

Pre-allocates and maintains a pool of persistent connections to each MCP server, eliminating per-request connection overhead and cold-start latency. The session pool manager maintains a configurable pool size per server, reuses connections across multiple client requests, and implements connection health checks with automatic reconnection on failure. Sessions are borrowed from the pool on client request and returned after tool invocation completes, with idle timeout and maximum lifetime policies to prevent resource leaks.

Provides a declarative configuration system for defining MCP servers, namespaces, and endpoints via a Next.js UI and tRPC backend, with all configurations persisted in PostgreSQL via Drizzle ORM. Administrators define which MCP servers to connect to, which tools to aggregate into which namespaces, and which endpoints to expose publicly. Configuration changes are applied dynamically without requiring server restart, with validation and conflict detection to prevent invalid configurations.

Provides a web-based inspector UI for testing tool invocations, viewing tool schemas, and debugging MCP server behavior. The inspector allows administrators to select a tool from any namespace, construct input parameters via a form or JSON editor, invoke the tool, and view the response. Request/response history is maintained for debugging, with detailed error messages and server logs visible in the UI.

Enables namespace-specific tool customization via a declarative override system that modifies tool names, descriptions, input/output schemas, and visibility without forking upstream servers. Overrides are applied at query time via the middleware pipeline, allowing different namespaces to present different versions of the same tool. The system supports renaming tools, hiding tools, modifying parameter schemas, and adding custom metadata.

Packages MetaMCP as a Docker container with all dependencies (Node.js, PostgreSQL client, MCP libraries) included, enabling single-command deployment. The Docker image includes the Next.js frontend, Node.js backend, and all configuration management logic. Environment variables control database connection, authentication providers, and MCP server endpoints, enabling configuration without rebuilding the image.