DOCSEARCHbyAlgolia
Submit Docs

MetaMCP Documentation

repository·ai-dev·Indexed 25 days ago

https://github.com/metatool-ai/metamcp

MetaMCP is an MCP (Model Context Protocol) proxy and orchestrator that aggregates multiple MCP servers into a single, unified endpoint. It provides features for namespace management, middleware, tool overrides, and built-in authentication (API-Key or OAuth). The platform supports STDIO MCP servers, SSE and Streamable HTTP transports, and includes deployment guides for Docker Compose and Kubernetes.

Tokens
54.7K
Snippets
136
Records
262
Agent score
81%

What's inside MetaMCP

  1. What is MetaMCP?

    ai-dev

    MetaMCP is an MCP (Model Context Protocol) proxy that acts as an aggregator, orchestrator, middleware, and gateway. It allows you to dynamically aggregate multiple MCP servers into a single, unified MetaMCP server. Because MetaMCP itself is an MCP server, it can be plugged into any MCP-compatible client.

    Key capabilities include:

    • Aggregation: Grouping MCP servers into namespaces and hosting them via unified endpoints (SSE or Streamable HTTP).
    • Orchestration: Enabling/disabling servers or specific tools at the namespace level.
    • Middleware: Applying pluggable logic (like tool filtering or observability) to MCP requests and responses.
    • Security: Adding authentication (API-Key or OAuth) to your MCP endpoints.
    • Inspection: Using a built-in inspector with saved server configurations to debug endpoints.

  2. MetaMCP Use Cases

    ai-dev

    MetaMCP is designed as infrastructure for developers to build agents on top of unified MCP endpoints. Key use cases include:

    • Grouping and Hosting: Grouping multiple MCP servers into namespaces and assigning authentication to public endpoints (SSE or Streamable HTTP).
    • Tool Selection: Selecting only specific tools from multiple MCP servers during re-mixing and applying middleware for observability and security.
    • Enhanced Inspector: Using MetaMCP as an advanced MCP inspector with saved server configurations.
    • Context Engineering: Using MetaMCP as an Elasticsearch-like engine for MCP tool selection (upcoming feature).

  3. What is an MCP Server in MetaMCP?

    ai-dev

    An MCP Server is a configuration that defines how MetaMCP starts and manages a Model Context Protocol server. These servers act as the building blocks of MetaMCP, providing tools, resources, and prompts that are aggregated and exposed through MetaMCP endpoints. A server configuration specifies the execution method (command/args or URL), the server type, authentication requirements, and resource dependencies.

    {
  "name": "HackerNews",
  "type": "STDIO", 
  "command": "uvx",
  "args": ["mcp-hn"],
  "description": "Access HackerNews stories and comments"
}

  4. How MetaMCP orchestrates MCP servers

    ai-dev

    MetaMCP acts as an aggregator and gateway between an MCP Client (such as Claude Desktop) and multiple installed MCP Servers.

    1. Tool Discovery: When a client requests a list of tools, MetaMCP iterates through all installed MCP servers, calls their list_tools method, aggregates the results, and applies any configured middleware before returning the unified list to the client.
    2. Tool Execution: When a client calls a tool, MetaMCP routes the call_tool request to the specific target MCP server, receives the response, and forwards it back to the client.

  5. How the MetaMCP OAuth 2.1 flow works

    ai-dev

    MetaMCP implements an OAuth 2.1 flow using Dynamic Registration and the PKCE (Proof Key for Code Exchange) Authorization Code Flow. This ensures secure authorization for MCP Clients without requiring a client secret to be stored on the client side.

    The Flow Steps:

    1. Dynamic Registration: The Client registers itself with the MetaMCP OAuth Server via POST /oauth/register to obtain a client_id and service endpoints.
    2. PKCE Generation: The Client generates a code_verifier and a code_challenge.
    3. Authorization Request: The Client redirects the User to /oauth/authorize including the client_id and code_challenge.
    4. User Authentication: If the user is not logged in, the MetaMCP server redirects them to a login page. Once authenticated, the server redirects back to the Client with an authorization code.
    5. Token Exchange: The Client exchanges the code and the original code_verifier via POST /oauth/token. The server verifies the PKCE (S256) to ensure the request is legitimate.
    6. API Access: The Client uses the resulting access_token in the Authorization: Bearer header to access protected MetaMCP API resources.
    sequenceDiagram
    participant Client as MCP Client
    participant Auth as MetaMCP OAuth Server
    participant User as User/Browser
    participant API as MetaMCP API
    
    Note over Client,API: OAuth 2.1 Dynamic Registration & Authorization Flow
    
    Client->>Auth: POST /oauth/register<br/>{redirect_uris, client_name, ...}
    Auth-->>Client: {client_id, endpoints, security_note}
    
    Note over Client,Auth: PKCE Authorization Code Flow
    
    Client->>Client: Generate code_verifier & code_challenge
    Client->>User: Redirect to /oauth/authorize<br/>?client_id=...&code_challenge=...
    User->>Auth: GET /oauth/authorize (with PKCE)
    
    alt User Not Authenticated
        Auth-->>User: Redirect to /login
        User->>Auth: Login credentials
        Auth-->>User: Redirect back to authorize
    end
    
    Auth-->>User: Redirect to client<br/>?code=...&state=...
    User->>Client: Authorization code received
    
    Client->>Auth: POST /oauth/token<br/>{code, code_verifier, client_id}
    Auth->>Auth: Verify PKCE (S256)
    Auth-->>Client: {access_token, token_type, expires_in}
    
    Client->>API: API Request<br/>Authorization: Bearer {access_token}
    API-->>Client: Protected resource response

  6. How MetaMCP middleware works

    ai-dev

    Middleware in MetaMCP allows you to intercept and transform Model Context Protocol (MCP) requests and responses at the namespace level. This enables adding functionality like filtering, logging, validation, and security without modifying individual MCP servers.

    Middleware Flow: MCP Client → Namespace → Middleware 1 → Middleware 2 → MCP Server
    MCP Client ← Namespace ← Middleware 2 ← Middleware 1 ← MCP Server

    Each middleware can modify the request before it reaches the server and the response before it returns to the client.

  7. Supported MCP Server Types

    ai-dev

    MetaMCP supports three communication types for MCP servers:

    1. STDIO: The most common type. Communicates via standard input/output. Ideal for Python packages installed via uvx, Node.js packages via npx, or custom executable scripts.
    2. SSE (Server-Sent Events): Communicates via SSE. Requires a url and optionally a bearerToken for authentication.
    3. STREAMABLE_HTTP: The standard for remote MCP. Communicates via HTTP streaming. Requires a url and optionally a bearerToken.

    Note on Authentication: If a server uses OAuth, you can leave the bearerToken empty.

    // STDIO Example
{
  "type": "STDIO",
  "command": "uvx", 
  "args": ["mcp-server-package"],
  "env": {
    "API_KEY": "your-api-key"
  }
}

// SSE Example
{
  "type": "SSE",
  "url": "https://api.example.com/sse",
  "bearerToken": "your-bearer-token"
}

// STREAMABLE_HTTP Example
{
  "type": "STREAMABLE_HTTP",
  "url": "https://api.example.com/mcp",
  "bearerToken": "your-bearer-token"
}

  8. Understand Audit Logs in MetaMCP

    ai-dev

    Audit Logs provide comprehensive visibility into all MCP tool calls made through MetaMCP. They allow you to track requests by API key, endpoint, server, and result status to monitor usage patterns, debug issues, and ensure security compliance.

    Each audit log entry captures the following metadata:

    • API 密钥 (API Key): The key used for authentication.
    • 端点 (Endpoint): The MetaMCP endpoint that handled the request.
    • 命名空间 (Namespace): The namespace context of the request.
    • MCP 服务器 (MCP Server): The target MCP server processing the tool call.
    • 工具 (Tool): The specific tool being invoked.
    • 状态 (Status): Whether the request succeeded or failed.
    • 持续时间 (Duration): Processing time in milliseconds.
    • 错误详情 (Error Details): The full error message for failed requests.

  9. How Namespaces work in MetaMCP

    ai-dev

    A Namespace is a logical grouping of MCP servers that allows you to aggregate tools from multiple servers into a single, unified MCP endpoint.

    When a namespace is configured:

    1. Server Selection: You choose which MCP servers belong to the namespace.
    2. Automatic Discovery: Tools from all active servers within the namespace are automatically discovered.
    3. Tool Prefixing: To prevent naming collisions, tools are automatically prefixed with their server name using the pattern {ServerName}__{originalToolName}.
    4. Unified Access: The namespace can be exposed via a single public endpoint, providing standard MCP protocol support, REST API access for each tool, and automatically generated OpenAPI documentation.
    {
  "name": "development-tools",
  "description": "Essential development tools",
  "servers": [
    {
      "name": "filesystem",
      "status": "ACTIVE",
      "tools": ["read_file", "write_file", "list_directory"]
    },
    {
      "name": "git-helper", 
      "status": "ACTIVE",
      "tools": ["git_status", "git_commit", "git_diff"]
    }
  ]
}

  10. Reduce MCP cold start times

    ai-dev

    MetaMCP attempts to reduce cold start times by pre-allocating idle sessions for configured MCP servers. By default, each server is allocated 1 idle session.

    If your MCP servers depend on specific system dependencies (other than uvx or npx), you should create a custom Dockerfile that installs these dependencies pre-emptively to ensure they are available immediately upon session activation.

  11. Configure MCP Servers in MetaMCP

    ai-dev

    An MCP Server configuration tells MetaMCP how to launch and manage Model Context Protocol servers. These servers provide tools, resources, and prompts that are aggregated and exposed via MetaMCP endpoints. Each configuration defines the startup method (command, arguments, environment), the server type, authentication requirements, and resource dependencies.

    {
  "name": "HackerNews",
  "type": "STDIO", 
  "command": "uvx",
  "args": ["mcp-hn"],
  "description": "访问 HackerNews 故事和评论"
}

  12. How Namespaces handle tool naming and discovery

    ai-dev

    When servers are added to a namespace, MetaMCP performs the following:

    1. Automatic Discovery: Tools are automatically discovered from all active servers in the namespace.
    2. Tool Prefixing: To prevent naming conflicts, tools are prefixed with their server name using the pattern {ServerName}__{originalToolName}.
    3. Nested Prefixing: When chaining MetaMCP gateways, prefixes can nest (e.g., OuterServer__InnerServer__my_tool).
    4. Filtering: Inactive tools are automatically filtered out of listings.

    Example Tool Mapping:

    • A search tool from a WebSearch server becomes WebSearch__search.