AI

MetaMCP: The Complete Guide to MCP Aggregation, Orchestration, and Gateway Management

Tosin Akinosho

— 3 min read
MetaMCP: The Complete Guide to MCP Aggregation, Orchestration, and Gateway Management
MetaMCP Logo

Introduction

MetaMCP is a powerful MCP (Model Context Protocol) aggregator, orchestrator, middleware, and gateway that allows you to dynamically aggregate multiple MCP servers into a unified endpoint. As a comprehensive solution packaged in Docker, MetaMCP enables developers to build sophisticated AI agent infrastructures with enhanced observability, security, and scalability.

Table of Contents

Key Features

  • MCP Aggregation: Group multiple MCP servers into unified namespaces
  • Dynamic Orchestration: Apply middleware and transform MCP requests/responses
  • Multiple Transports: Support for SSE, Streamable HTTP, and OpenAPI endpoints
  • Authentication: API key auth, OAuth, and OIDC provider support
  • Multi-tenancy: Designed for organizations with private/public access scopes
  • Enhanced Inspector: Debug MetaMCP endpoints with saved server configs
  • Middleware System: Pluggable middleware for observability and security

Core Concepts

MCP Server

A configuration that tells MetaMCP how to start an MCP server:

"HackerNews": {
  "type": "STDIO",
  "command": "uvx",
  "args": ["mcp-hn"]
}

MetaMCP Namespace

Groups one or more MCP servers, enables/disables tools, and applies middleware to requests and responses.

MetaMCP Endpoint

Creates public endpoints with namespace assignment, supporting multiple authentication methods and transport protocols.

Installation & Setup

git clone https://github.com/metatool-ai/metamcp.git
cd metamcp
./setup-docker.sh

Or manually:

cp example.env .env
docker compose up -d

Podman (RHEL/Fedora)

For Red Hat-based systems with enhanced security:

git clone https://github.com/metatool-ai/metamcp.git
cd metamcp
./setup-podman.sh

Podman Benefits:

  • 🔒 Rootless containers (enhanced security)
  • 🚫 No daemon required (systemd integration)
  • 🛡️ Better SELinux integration
  • 📦 Native to Red Hat ecosystem

Local Development

pnpm install
pnpm dev

Configuration

Environment Variables

Key configuration options in your .env file:

# Basic Configuration
APP_URL=http://localhost:12008
DATABASE_URL=postgresql://postgres:password@localhost:5432/metamcp

# Authentication
BETTER_AUTH_SECRET=your-secret-key
BETTER_AUTH_URL=http://localhost:12008

# OIDC Support (Optional)
OIDC_CLIENT_ID=your-oidc-client-id
OIDC_CLIENT_SECRET=your-oidc-client-secret
OIDC_DISCOVERY_URL=https://your-provider.com/.well-known/openid-configuration

MCP Client Configuration

Example mcp.json for Cursor:

{
  "mcpServers": {
    "MetaMCP": {
      "url": "http://localhost:12008/metamcp//sse"
    }
  }
}

Claude Desktop Configuration

Using mcp-proxy for STDIO-only clients:

{
  "mcpServers": {
    "MetaMCP": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "--transport",
        "streamablehttp",
        "http://localhost:12008/metamcp//mcp"
      ],
      "env": {
        "API_ACCESS_TOKEN": ""
      }
    }
  }
}

Usage Examples

Creating MCP Servers

Configure your MCP servers in the MetaMCP interface:

// Example server configuration
const serverConfig = {
  name: "HackerNews",
  type: "STDIO",
  command: "uvx",
  args: ["mcp-hn"],
  env: {}
};

Setting Up Namespaces

Group servers into logical namespaces:

// Create namespace with multiple servers
const namespace = {
  name: "news-aggregator",
  servers: ["HackerNews", "RedditAPI"],
  middleware: ["filter-inactive-tools"]
};

Creating Endpoints

Expose namespaces through public endpoints:

// Endpoint configuration
const endpoint = {
  name: "public-news",
  namespace: "news-aggregator",
  transport: "sse", // or "streamablehttp", "openapi"
  auth: "api-key" // or "oauth"
};

Advanced Features

OIDC Authentication

MetaMCP supports enterprise SSO integration with popular providers:

  • Auth0: https://your-domain.auth0.com/.well-known/openid-configuration
  • Keycloak: https://your-keycloak.com/realms/your-realm/.well-known/openid-configuration
  • Azure AD: https://login.microsoftonline.com/your-tenant-id/v2.0/.well-known/openid-configuration

Middleware System

Apply transformations to MCP requests and responses:

// Built-in middleware example
const middleware = {
  name: "filter-inactive-tools",
  description: "Optimizes tool context for LLMs",
  enabled: true
};

Multi-tenancy Support

MetaMCP supports both private and public access scopes:

  • Users can create private MCPs, namespaces, and endpoints
  • Public API keys cannot access private MetaMCPs
  • Organizations can deploy on their own infrastructure

Cold Start Optimization

MetaMCP pre-allocates idle sessions for configured MCP servers to reduce cold start time. Customize the Dockerfile to install additional dependencies:

# Custom Dockerfile example
FROM metamcp:latest
RUN apt-get update && apt-get install -y your-dependencies

Conclusion

MetaMCP transforms how developers build and deploy AI agent infrastructures by providing a unified platform for MCP server aggregation, orchestration, and management. With its comprehensive feature set including multi-tenancy, OIDC authentication, middleware system, and multiple transport protocols, MetaMCP enables scalable, secure, and maintainable AI agent deployments.

For more expert insights and tutorials on AI and automation, visit us at decisioncrafters.com.

MetaMCP Screenshot

Read more