MetaMCP

Um middleware auto-hospedável para gerenciar todos os seus MCPs através de uma interface gráfica e um proxy local, com suporte a múltiplos clientes e espaços de trabalho.

GitHub
2.7k
Experimente este MCPPatrocinado

Documentação

🚀 MetaMCP (Agregador, Orquestrador, Middleware, Gateway MCP em um único docker)

📢 Atualização mais recente: Este branch ai-dev será o branch de desenvolvimento contínuo que contém alterações de agentes de IA. Por favor, teste antes de construir a imagem com base neste branch. Houve muitos PRs graças à comunidade, mas mesclá-los e revisá-los também tem sido um esforço crescente. Decidi incluir alterações de IA. Pelo menos até agora, a funcionalidade principal funciona. Há também um fork mantido pela comunidade (muito obrigado!): https://github.com/Umbrella-IT-Group/metamcp

📢 Atualização: [Do autor: peço desculpas por algum atraso recente na manutenção, mas continuarei pelo menos mesclando PRs, mais contexto aqui]

MetaMCP é um proxy MCP que permite agregar dinamicamente servidores MCP em um servidor MCP unificado e aplicar middlewares. O próprio MetaMCP é um servidor MCP, portanto pode ser facilmente conectado a QUALQUER cliente MCP.

MetaMCP Diagram

Para mais detalhes, considere visitar nosso site de documentação: https://docs.metamcp.com

English | 简体中文

📋 Sumário

🎯 Casos de Uso

  • 🏷️ Agrupe servidores MCP em namespaces, hospede-os como meta-MCPs e atribua endpoints públicos (SSE ou HTTP Streamable), com autenticação. Troque um namespace para um endpoint com um clique.
  • 🎯 Selecione apenas as ferramentas que você precisa ao remixar servidores MCP. Aplique outros middlewares plugáveis em torno de observabilidade, segurança, etc. (em breve)
  • 🔍 Use como inspetor MCP aprimorado com configurações de servidor salvas e inspecione seus endpoints MetaMCP internamente para ver se funcionam ou não.
  • 🔍 Use como Elasticsearch para seleção de ferramentas MCP (em breve)

Geralmente, os desenvolvedores podem usar o MetaMCP como infraestrutura para hospedar servidores MCP compostos dinamicamente por meio de um endpoint unificado e construir agentes sobre ele.

Vídeo de demonstração rápida: https://youtu.be/Cf6jVd2saAs

MetaMCP Screenshot

📖 Conceitos

🖥️ Servidor MCP

Uma configuração de servidor MCP que informa ao MetaMCP como iniciar um servidor MCP.

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

🔐 Variáveis de Ambiente & Segredos (Servidores MCP STDIO)

Para servidores MCP STDIO, o MetaMCP suporta três maneiras de lidar com variáveis de ambiente e segredos:

1. Valores Brutos - Valores de string diretos (não recomendado para segredos):

API_KEY=your-actual-api-key-here
DEBUG=true

2. Referências a Variáveis de Ambiente - Use a sintaxe ${ENV_VAR_NAME}:

API_KEY=${OPENAI_API_KEY}
DATABASE_URL=${DB_CONNECTION_STRING}

3. Correspondência Automática - Se o nome da variável de ambiente esperado em sua ferramenta corresponder à variável de ambiente do contêiner, você pode omiti-la completamente. O MetaMCP passará automaticamente as variáveis de ambiente correspondentes.

🔒 Nota de Segurança: Referências a variáveis de ambiente (${VAR_NAME}) são resolvidas a partir do ambiente do contêiner MetaMCP em tempo de execução. Isso mantém os valores reais dos segredos fora da sua configuração e do repositório git.

⚙️ Nota de Desenvolvimento: Para desenvolvimento local com pnpm run dev:docker, certifique-se de que suas variáveis de ambiente estejam listadas em turbo.json sob globalEnv para serem passadas aos processos de desenvolvimento. Isso não é necessário para implantações Docker em produção.

🏷️ Namespace MetaMCP

  • Agrupe um ou mais servidores MCP em um namespace
  • Habilite/desabilite servidores MCP ou em nível de ferramenta
  • Aplique middlewares a solicitações e respostas MCP
  • Substitua nomes/títulos/descrições de ferramentas por namespace e anexe anotações MCP personalizadas (ex.: { "annotations": { "readOnlyHint": false } })

🌐 Endpoint MetaMCP

  • Crie endpoints e atribua namespaces a eles
  • Múltiplos servidores MCP no namespace serão agregados e emitidos como um endpoint MetaMCP
  • Escolha entre Autenticação por Chave de API (no cabeçalho ou parâmetro de consulta) ou OAuth padrão na Especificação MCP 2025-06-18
  • Hospede por meio de transportes SSE ou HTTP Streamable em MCP e endpoints OpenAPI para clientes como Open WebUI

⚙️ Middleware

  • Intercepta e transforma solicitações e respostas MCP em nível de namespace
  • Exemplo integrado: "Filtrar ferramentas inativas" - otimiza o contexto de ferramentas para LLMs
  • Ideias futuras: registro de ferramentas, rastreamento de erros, validação, varredura

🔍 Inspetor

Semelhante ao inspetor MCP oficial, mas com configurações de servidor salvas - o MetaMCP cria configurações automaticamente para que você possa depurar endpoints MetaMCP imediatamente.

✏️ Substituições de Ferramentas & Anotações

  • Abra um namespace → aba Ferramentas para ver cada ferramenta proveniente dos servidores MCP conectados.
  • Cada ferramenta salva pode ser expandida e editada inline: atualize o nome/título/descrição de exibição ou forneça um blob JSON com anotações específicas do namespace (por exemplo, { "annotations": { "readOnlyHint": false } }).
  • Selos na tabela ("Substituído", "Anotações") mostram quais ferramentas possuem atualmente metadados personalizados. Passe o mouse sobre eles para ler uma dica descrevendo o que foi substituído.
  • As substituições de anotações são mescladas com o que o servidor MCP upstream retorna, para que você possa adicionar dicas de UI personalizadas com segurança sem perder os metadados do provedor.

🚀 Início Rápido

🐳 Executar com Docker Compose (Recomendado)

Clone o repositório, prepare o .env e inicie com docker compose:

git clone https://github.com/metatool-ai/metamcp.git
cd metamcp
cp example.env .env
docker compose up -d

Se você modificar as variáveis de ambiente APP_URL, certifique-se de acessar apenas pelo APP_URL, pois o MetaMCP aplica a política CORS na URL, portanto nenhuma outra URL é acessível.

Observe que o nome do volume pg pode colidir com outros dockers pg seus, que é global; considere renomeá-lo no docker-compose.yml:

volumes:
  metamcp_postgres_data:
    driver: local

📦 Construir ambiente de desenvolvimento com Dev Containers (VSCode/Cursor)

Você pode usar a extensão VSCode/Cursor para construir o ambiente de desenvolvimento em um contêiner.

Isso requer apenas que você tenha um ambiente executando Docker ou uma alternativa similar (o comando docker/docker compose é necessário), e nenhum outro componente dependente precisa ser instalado em sua máquina host.

  1. Primeiro, clone o código-fonte do MetaMCP e abra o projeto no Visual Studio Code.
git clone https://github.com/metatool-ai/metamcp.git
cd metamcp
code .
  1. Alterne para Dev Containers. Abra a Paleta de Comandos do VSCode e execute Dev Containers: Reopen in Container.

O VSCode abrirá o projeto Dev Containers em uma nova janela, onde construirá o runtime e instalará o toolchain de acordo com o Dockerfile antes de iniciar a conexão e, finalmente, instalar as dependências do MetaMCP. image

nota Este processo requer uma conexão de rede confiável, e acessará Docker Hub, GitHub e alguns outros sites. Você precisará garantir a conexão de rede por conta própria, caso contrário, a construção do contêiner pode falhar.

Aguarde alguns minutos; dependendo da conexão com a internet ou do desempenho do computador, pode levar de alguns minutos a dezenas de minutos. Você pode clicar na Barra de Progresso no canto inferior direito para visualizar um log ao vivo onde poderá verificar travamentos incomuns. image

Após terminar, você pode executar pnpm dev para iniciar o servidor de desenvolvimento.

💻 Desenvolvimento Local

Ainda recomendamos executar o postgres via docker para facilitar a configuração:

pnpm install
pnpm dev

🔌 Compatibilidade com o Protocolo MCP

  • ✅ Ferramentas, Recursos e Prompts suportados
  • ✅ Servidores MCP habilitados para OAuth testados para a versão 03-26

Se você tiver dúvidas, sinta-se à vontade para deixar issues no GitHub ou PRs.

🔗 Conectar ao MetaMCP

📝 Ex.: Cursor via mcp.json

Exemplo de mcp.json

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

🖥️ Conectando Claude Desktop e Outros Clientes Apenas-STDIO

Como os endpoints MetaMCP são apenas remotos (SSE, HTTP Streamable, OpenAPI), clientes que suportam apenas servidores stdio (como Claude Desktop) precisam de um proxy local para conectar.

Nota: Embora mcp-remote seja às vezes sugerido para esse propósito, ele é projetado para autenticação baseada em OAuth e não funciona com a autenticação por chave de API do MetaMCP. Com base em testes, mcp-proxy é a solução recomendada.

Aqui está uma configuração funcional para Claude Desktop usando mcp-proxy:

Usando HTTP Streamable

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

Usando SSE

{
  "mcpServers": {
    "ehn": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/sse"
      ],
      "env": {
        "API_ACCESS_TOKEN": "<YOUR_API_KEY_HERE>"
      }
    }
  }
}

Notas importantes:

  • Substitua <YOUR_ENDPOINT_NAME> pelo nome real do seu endpoint
  • Substitua <YOUR_API_KEY_HERE> pela sua chave de API MetaMCP (formato: sk_mt_...)

Para mais detalhes e abordagens alternativas, veja issue #76.

🔧 Solução de Problemas de Autenticação por Chave de API

  • A autenticação por chave de API no parâmetro ?api_key= não funciona para SSE. Funciona apenas para HTTP Streamable e OpenAPI.
  • A melhor prática é usar a chave de API no cabeçalho Authorization: Bearer <API_KEY>.
  • Tente desabilitar a autenticação temporariamente quando enfrentar problemas de conexão para ver se é um problema de autenticação.

❄️ Problema de Inicialização a Frio e Dockerfile Personalizado

  • O MetaMCP pré-aloca sessões ociosas para cada servidor MCP e MetaMCP configurado. A sessão ociosa padrão para cada um é 1, o que pode ajudar a reduzir o tempo de inicialização a frio.
  • Se o seu MCP exigir dependências além de uvx ou npx, você precisará personalizar o Dockerfile para instalar as dependências por conta própria.
  • Consulte invalidation.md para um diagrama de sequência sobre como a sessão ociosa é invalidada durante atualizações.

🛠️ Solução: Personalize o Dockerfile para adicionar dependências ou pré-instalar pacotes para reduzir o tempo de inicialização a frio.

🧾 Níveis de Log

O backend do MetaMCP grava logs em arquivos e, opcionalmente, espelha níveis selecionados no console. Controle o espelhamento do console com a variável de ambiente LOG_LEVEL.

  • Arquivos

    • app.log: recebe DEBUG, INFO e WARN
    • error.log: recebe ERROR

  • Espelhamento no console (LOG_LEVEL)

    • all: espelha DEBUG, INFO, WARN, ERROR no console
    • info: espelha apenas INFO no console
    • errors-only: espelha WARN e ERROR no console
    • none: sem saída no console

  • Padrões e exemplos

    • Padrão (quando não definido ou inválido): errors-only
    • Exemplo de .env: 
      LOG_LEVEL='errors-only' # 'all', 'info', 'errors-only', 'none'
    • docker-compose.dev.yml usa: LOG_LEVEL: ${LOG_LEVEL:-all}

🔐 Autenticação

  • 🛡️ Better Auth para frontend e backend (procedimentos TRPC)
  • 🍪 Cookies de sessão garantem conexões seguras de proxy MCP internas
  • 🔑 Autenticação por chave de API para acesso externo via cabeçalho Authorization: Bearer <api-key>
  • 🪪 MCP OAuth: Endpoints expostos têm opções para usar OAuth padrão no MCP Spec 2025-06-18, fácil de conectar.
  • 🏢 Multi-inquilino: Projetado para organizações implantarem em suas próprias máquinas. Suporta escopos de acesso privado e público. Usuários podem criar MCPs, namespaces, endpoints e chaves de API para si mesmos ou para todos. Chaves de API públicas não podem acessar MetaMCPs privados.
  • ⚙️ Controles de Registro Separados: Administradores podem controlar independentemente o registro de UI e o registro SSO/OAuth através da página de configurações, permitindo cenários flexíveis de implantação empresarial.

🚦 Gerenciamento de Tráfego

🚧 Limite de Taxa MCP

O recurso de Limite de Taxa MCP permite definir o máximo de requisições que uma ferramenta MCP (um endpoint) aceitará em um determinado intervalo de tempo. Existem duas estratégias diferentes para definir limites que você pode usar separadamente ou em conjunto:

  • Endpoint rate-limiting (Rate Limiting): aplica-se simultaneamente a todos os clientes que usam o endpoint, compartilhando um contador único.
  • User rate-limiting (Client Rate Limiting): define um contador para cada usuário individual.

Ambos os tipos podem coexistir e se complementam, e armazenam os contadores em memória. Em um cluster, cada máquina vê e conta apenas o tráfego que passa por ela.

Limite de taxa de endpoint

O limite de taxa de endpoint atua no número de transações simultâneas que um endpoint pode processar. Esse tipo de limite protege o serviço para todos os clientes. Quando os usuários conectados a um endpoint juntos excedem o rate-limiting, o MetaMCP começa a rejeitar conexões com um código de status 503 Service Unavailable.

Opções de limite de taxa de endpoint

  • Max Rate: Define quantas requisições você aceitará de todos os usuários juntos em qualquer instante. Quando o gateway inicia, o balde está cheio. À medida que as requisições dos usuários chegam, os tokens restantes no balde diminuem. Ao mesmo tempo, o limitador de taxa reabastece o balde na taxa desejada até atingir sua capacidade máxima.
  • Max Rate Seconds: Período de tempo em que as taxas máximas operam em segundos. Por exemplo, se você definir um máximo de segundos de taxa de 60s e um limite de taxa de 5, você está permitindo 5 requisições a cada sessenta segundos.

Limite de taxa de usuário

O limite de taxa do cliente ou usuário aplica um contador para cada usuário individual e endpoint. Quando um único usuário conectado a um endpoint excede seu client-max-rate, o MetaMCP começa a rejeitar conexões com um código de status 429 Too Many Requests

Opções de limite de taxa de usuário

  • Client Max Rate: Número de tokens que você adiciona ao Token Bucket para cada usuário individual (cota do usuário) no intervalo de tempo desejado (Client Max Rate Seconds). Os tokens restantes no balde são as requisições que um usuário específico pode fazer.
  • Client Max Rate Seconds: Período de tempo em que as taxas máximas operam em segundos. Por exemplo, se você definir um intervalo de 60s e uma taxa de 5, você está permitindo 5 requisições a cada sessenta segundos.
  • Client Max Rate Strategy: Define a estratégia que você usará para definir contadores de cliente. Escolha "ip" quando as restrições se aplicarem ao endereço IP do cliente, ou defina como "header" quando houver um cabeçalho que identifique um usuário de forma única. Esse cabeçalho deve ser definido com a entrada de chave.
  • Client Max Rate Strategy Key: É o nome do cabeçalho que contém a identificação do usuário (por exemplo, Authorization em tokens, ou X-Original-Forwarded-For para IPs).

🔗 Suporte a Provedores OpenID Connect (OIDC)

O MetaMCP suporta autenticação OpenID Connect para integração SSO empresarial. Isso permite que organizações usem seus provedores de identidade existentes (Auth0, Keycloak, Azure AD, etc.) para autenticação.

🛠️ Configuração

Adicione as seguintes variáveis de ambiente ao seu arquivo .env:

# Required
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

# Optional customization
OIDC_PROVIDER_ID=oidc
OIDC_SCOPES=openid email profile
OIDC_PKCE=true

🏢 Provedores Suportados

O MetaMCP foi testado com provedores OIDC populares:

  • 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
  • Google: https://accounts.google.com/.well-known/openid-configuration
  • Okta: https://your-domain.okta.com/.well-known/openid-configuration

🔒 Recursos de Segurança

  • 🔐 PKCE (Proof Key for Code Exchange) habilitado por padrão
  • 🛡️ Fluxo de Código de Autorização com criação automática de usuário
  • 🔄 Descoberta automática de endpoints OIDC
  • 🍪 Gerenciamento de sessão contínuo com o sistema de autenticação existente

📱 Uso

Uma vez configurado, os usuários verão um botão "Entrar com OIDC" na página de login, junto com o formulário de e-mail/senha. O fluxo de autenticação cria automaticamente novos usuários no primeiro login.

Para exemplos de configuração mais detalhados e solução de problemas, consulte CONTRIBUTING.md.

⚙️ Controles de Registro

O MetaMCP fornece controles separados para diferentes métodos de registro, permitindo que administradores ajustem as políticas de acesso do usuário para implantações empresariais.

🎛️ Controles Disponíveis

  • Registro de UI: Controla se os usuários podem criar contas através do formulário de registro
  • Registro SSO: Controla se os usuários podem criar contas através de provedores SSO/OAuth (OIDC, etc.)

🏢 Casos de Uso Empresariais

Essa separação permite cenários empresariais comuns:

  • Bloquear registro de UI, permitir SSO: Impedir cadastros manuais enquanto permite usuários SSO corporativos
  • Bloquear registro SSO, permitir UI: Permitir cadastros manuais enquanto restringe o acesso SSO
  • Bloquear ambos: Desabilitar completamente o registro de novos usuários
  • Permitir ambos: Comportamento padrão para implantações abertas

🛠️ Configuração

Acesse a página Configurações na interface de administração do MetaMCP para configurar esses controles:

  1. Navegue até Configurações → Configurações de Autenticação
  2. Alterne "Desabilitar Registro de UI" para controlar cadastros baseados em formulário
  3. Alterne "Desabilitar Registro SSO" para controlar cadastros OAuth/OIDC

Ambos os controles funcionam de forma independente, dando a você total flexibilidade sobre sua política de registro.

🌐 Implantação Personalizada e configuração SSE para Nginx

Se você quiser implantá-lo em um serviço online ou um VPS, é necessária uma instância com pelo menos 2GB-4GB de memória. E quanto maior o tamanho, melhor o desempenho.

Como o MCP utiliza SSE para conexões longas, se você estiver usando um proxy reverso como nginx, consulte um exemplo de configuração nginx.conf.example

🏗️ Arquitetura

  • Frontend: Next.js
  • Backend: Express.js com tRPC, hospedando MCPs através do TS SDK e proxy interno
  • Auth: Better Auth
  • Estrutura: Monorepo independente com Turborepo e publicação Docker

📊 Diagrama de Sequência

Nota: Prompts e recursos seguem padrões semelhantes aos das ferramentas.

sequenceDiagram
    participant MCPClient as MCP Client (e.g., Claude Desktop)
    participant MetaMCP as MetaMCP Server
    participant MCPServers as Installed MCP Servers

    MCPClient ->> MetaMCP: Request list tools

    loop For each listed MCP Server
        MetaMCP ->> MCPServers: Request list_tools
        MCPServers ->> MetaMCP: Return list of tools
    end

    MetaMCP ->> MetaMCP: Aggregate tool lists & apply middleware
    MetaMCP ->> MCPClient: Return aggregated list of tools

    MCPClient ->> MetaMCP: Call tool
    MetaMCP ->> MCPServers: call_tool to target MCP Server
    MCPServers ->> MetaMCP: Return tool response
    MetaMCP ->> MCPClient: Return tool response

🗺️ Roteiro

Próximos passos potenciais:

  • 🔌 Acesso à API de Administração Headless
  • 🔍 Aplicar dinamicamente regras de busca em endpoints MetaMCP
  • 🛠️ Mais middlewares
  • 💬 Playground de Chat/Agente
  • 🧪 Testes e Avaliação para otimização de seleção de ferramentas MCP
  • ⚡ Gerar dinamicamente servidores MCP

🌐 i18n

Veja README-i18n.md

Atualmente, os locais en e zh são suportados, mas contribuições são bem-vindas.

🤝 Contribuindo

Aceitamos contribuições! Veja detalhes em CONTRIBUTING.md

📄 Licença

MIT

Agradeceríamos se você mencionasse com links de volta se seus projetos usarem o código.

🙏 Créditos

Algum código inspirado por:

Não usei diretamente o código, mas tirei ideias de