O que é um registry de ferramentas MCP?

É um catálogo centralizado que descreve todos os MCP servers e ferramentas disponíveis na empresa, com metadados como endpoint, versão, permissões necessárias e tenants autorizados. Funciona como um 'cardápio' que os agentes consultam para saber o que podem usar, sem precisar de configuração manual em cada cliente MCP.

Qual a diferença entre um registry MCP e a configuração estática de servidores?

A configuração estática (ex.: claude_desktop_config.json) define manualmente os servidores disponíveis em cada máquina cliente. O registry centraliza esse catálogo num endpoint HTTP consultável: quando um novo servidor é adicionado, todos os clientes que consultam o registry o encontram automaticamente, sem atualização manual.

Como o registry lida com diferentes perfis de permissão por usuário?

O registry aceita o token de autenticação do agente e devolve apenas os servidores e ferramentas que aquele perfil tem permissão de usar. Um agente de atendimento vê ferramentas de CRM; um agente de dados vê ferramentas de analytics. Isso é feito via filtro no campo tenants_allowed e scopes dentro de cada entry do catálogo.

MCP · MOFU · TI

Registry interno de ferramentas MCP por tenant e perfil: como centralizar seu catálogo

Por Adriano Schneider · 5 de maio de 2026 · 8 min de leitura

Quando uma empresa tem 3 MCP servers e 2 times usando, a configuração manual funciona. Quando chega a 8 servidores e 6 times, vira um pesadelo de manutenção — alguém sempre com a versão errada, alguém sem acesso ao servidor certo. A solução é um registry centralizado: um catálogo vivo que cada agente consulta para saber o que existe e o que pode usar.

Por que centralizar o catálogo de ferramentas

Sem um registry centralizado, cada time que quer usar um MCP server precisa:

Descobrir que o servidor existe (por e-mail, Slack, documentação desatualizada no Confluence).
Saber o endpoint correto e a versão atual.
Configurar manualmente o cliente MCP com essas informações.
Repetir tudo isso quando o servidor muda de versão ou endpoint.

Isso funciona para 2 ou 3 servidores. Para qualquer coisa além disso, você está criando débito técnico operacional: horas por semana de time sênior fazendo suporte de configuração.

O registry resolve o problema de discovery de forma análoga ao que um DNS faz para IPs: em vez de memorizar e distribuir endereços, você consulta um serviço central que tem a informação atualizada.

O que o registry precisa conter

Um registry MCP eficiente não é só uma lista de URLs. Ele precisa conter metadados suficientes para que um agente (ou um desenvolvedor) entenda o que cada server faz, quem pode usá-lo e como se autenticar.

Campos obrigatórios por entrada no registry:

name: identificador único do servidor, em kebab-case.
description: o que este servidor faz em 1–2 frases. Esse texto pode ser injetado no system prompt do agente.
endpoint: URL base do servidor MCP.
version: versão semântica atual (SemVer).
permissions: lista de scopes necessários para se autenticar neste servidor.
scopes: lista de scopes que as ferramentas deste servidor disponibilizam.
tenants_allowed: lista de tenant IDs autorizados (ou "*" para qualquer tenant).
rate_limit: limite de chamadas por janela de tempo.
status: ativo, beta, depreciado ou inativo.
deprecation_date: data prevista de remoção (se status: depreciado).
contact: time ou pessoa responsável pelo servidor.

Esquema YAML/JSON do registry: exemplo completo

Abaixo está um exemplo de registry com três servidores MCP — a estrutura que recomendo como ponto de partida. Você pode manter isso como arquivo YAML servido por um endpoint HTTP simples ou como banco de dados com API.

# mcp-registry.yaml
# Versão do schema do registry (independente da versão dos servidores)
schema_version: "1.0"
atualizado_em: "2026-05-05T10:00:00-03:00"

servidores:
  - name: mcp-crm
    description: >
      Ferramentas de CRM interno: busca de clientes, pedidos, tickets de suporte
      e histórico de interações. Use para fluxos de atendimento e pós-venda.
    endpoint: "https://mcp.interno.empresa.com/crm"
    version: "2.1.0"
    status: ativo
    contact: "time-produto@empresa.com"
    autenticacao:
      tipo: jwt_bearer
      issuer: "https://auth.interno.empresa.com"
      audience: "mcp-crm"
    permissions:
      - crm:acesso  # scope mínimo para se conectar ao servidor
    scopes:
      - pedidos:leitura
      - pedidos:escrita
      - clientes:leitura
      - clientes:escrita
      - tickets:leitura
      - tickets:escrita
    tenants_allowed:
      - "*"  # todos os tenants autorizados internamente
    rate_limit:
      chamadas: 100
      janela: "1m"
      por: agente
    ferramentas:
      - name: buscar_pedido
        version: "1.2.0"
        scopes_necessarios: [pedidos:leitura]
      - name: listar_clientes
        version: "1.0.3"
        scopes_necessarios: [clientes:leitura]
      - name: criar_ticket_suporte
        version: "2.0.0"
        scopes_necessarios: [tickets:escrita]
      - name: buscar_contato_v1
        version: "1.5.2"
        status: depreciado
        deprecation_date: "2026-06-30"
        substituto: buscar_cliente_v2

  - name: mcp-analytics
    description: >
      Ferramentas de analytics e relatórios: dashboards de vendas, funil de conversão,
      churn e métricas de produto. Somente leitura — não escreve em banco de dados.
    endpoint: "https://mcp.interno.empresa.com/analytics"
    version: "1.3.0"
    status: ativo
    contact: "time-dados@empresa.com"
    autenticacao:
      tipo: jwt_bearer
      issuer: "https://auth.interno.empresa.com"
      audience: "mcp-analytics"
    permissions:
      - analytics:acesso
    scopes:
      - relatorios:leitura
      - metricas:leitura
      - exportacao:leitura
    tenants_allowed:
      - "tenant-empresa-abc"
      - "tenant-empresa-xyz"
      # tenants externos não têm acesso a analytics interno
    rate_limit:
      chamadas: 30
      janela: "1m"
      por: agente
    ferramentas:
      - name: relatorio_vendas_mes
        version: "1.1.0"
        scopes_necessarios: [relatorios:leitura]
      - name: taxa_churn_periodo
        version: "1.0.0"
        scopes_necessarios: [metricas:leitura]
      - name: exportar_csv_pedidos
        version: "1.2.0"
        scopes_necessarios: [exportacao:leitura]

  - name: mcp-financeiro
    description: >
      Ferramentas financeiras: consulta de notas fiscais, extrato de cobranças,
      status de inadimplência e geração de boletos. Acesso restrito a tenants autorizados.
    endpoint: "https://mcp.interno.empresa.com/financeiro"
    version: "3.0.0"
    status: ativo
    contact: "time-financeiro@empresa.com"
    autenticacao:
      tipo: jwt_bearer
      issuer: "https://auth.interno.empresa.com"
      audience: "mcp-financeiro"
    permissions:
      - financeiro:acesso
    scopes:
      - notas:leitura
      - cobrancas:leitura
      - boletos:escrita
    tenants_allowed:
      - "tenant-financeiro-interno"
      # Este servidor não é exposto para tenants de clientes
    rate_limit:
      chamadas: 20
      janela: "1m"
      por: agente

Como o discovery automático funciona

Com o registry no ar, o fluxo de descoberta de um agente funciona assim:

Agente faz login: obtém um JWT com os claims de tenant_id, agent_id e a lista de scopes que tem permissão.
Agente consulta o registry: faz um GET para https://registry.interno.empresa.com/mcp/servidores com o JWT no header. O registry filtra e retorna apenas os servidores onde o tenant está em tenants_allowed e o agente tem pelo menos um dos permissions necessários.
Agente configura seus clientes MCP: com a lista retornada, o agente sabe a quais servidores se conectar, qual endpoint usar e quais ferramentas estão disponíveis para ele.
Cache com TTL: o agente guarda a lista em memória por um período configurável (padrão: 5 minutos). Isso evita uma consulta ao registry a cada chamada de ferramenta.

O endpoint principal do registry deve ter um schema como este:

GET /mcp/servidores
Authorization: Bearer {jwt}

Response 200:
{
  "schema_version": "1.0",
  "gerado_em": "2026-05-05T14:32:11-03:00",
  "cache_ttl_segundos": 300,
  "servidores": [
    {
      "name": "mcp-crm",
      "endpoint": "https://mcp.interno.empresa.com/crm",
      "version": "2.1.0",
      "ferramentas_disponiveis": [
        "buscar_pedido",
        "listar_clientes",
        "criar_ticket_suporte"
        // buscar_contato_v1 NÃO aparece aqui se foi depreciado e expirou
      ]
    }
    // somente servidores que este token pode acessar
  ]
}

Versionamento semântico no nível da ferramenta

O registry precisa rastrear versões em dois níveis: o servidor como um todo e cada ferramenta individualmente. Isso parece excesso de detalhe, mas é fundamental na prática.

Imagine que você tem o servidor MCP de CRM na versão 2.1.0. Dentro dele:

buscar_pedido está na v1.2.0 — estável, sem mudanças há 3 meses.
criar_ticket_suporte está na v2.0.0 — mudou o schema de input na major recente.
buscar_contato_v1 está depreciada — será removida em 30/06/2026.

Se você rastrear só a versão do servidor, qualquer time que tinha um agente funcionando com a v1 de criar_ticket vai quebrar sem aviso quando o servidor subir de versão. Com versionamento por ferramenta no registry, você pode manter v1 e v2 simultaneamente durante o período de migração.

Regras de versionamento SemVer para ferramentas MCP
Tipo de mudança	Versão afetada	Exemplo	Precisa de período de migração?
Correção interna sem mudança de interface	PATCH (0.0.X)	Corrigiu bug que retornava data em fuso errado	Não
Novo campo opcional no input ou output	MINOR (0.X.0)	Adicionou campo `urgencia` opcional no input de criar_ticket	Não (retrocompatível)
Nova ferramenta adicionada ao servidor	MINOR do servidor	Adicionou `reabrir_ticket`	Não
Campo obrigatório adicionado ao input	MAJOR (X.0.0)	Tornou `categoria` obrigatório em criar_ticket	Sim — mínimo 30 dias com ambas versões ativas
Campo removido ou renomeado no output	MAJOR (X.0.0)	Renomeou `status` para `situacao`	Sim — mínimo 30 dias com ambas versões ativas
Ferramenta removida do servidor	MAJOR do servidor	Removeu `buscar_contato_v1`	Sim — anunciar com no mínimo 60 dias de antecedência

Como estruturar o registry tecnicamente

Existem três abordagens, em ordem crescente de complexidade:

Arquivo YAML/JSON servido por CDN ou servidor estático. Ideal para começar. O registry é um arquivo que você versiona no Git e serve via S3, Cloudflare ou nginx. A desvantagem é que não tem lógica de filtro por tenant — você serve o catálogo completo e o cliente filtra. Funciona para times pequenos com poucos tenants.
API simples (FastAPI, Express, Gin). O registry vira um serviço HTTP que aceita o JWT, valida os claims e devolve o catálogo filtrado. Recomendado a partir de 3+ times usando MCP. Custo de infraestrutura baixo: uma instância pequena aguenta milhares de consultas por hora.
Registry federado com auto-registro. Cada MCP server, ao subir, registra a si mesmo no registry via API. Quando é desligado, cancela o registro. O registry mantém heartbeat de cada servidor e remove automaticamente os que não respondem. Essa é a abordagem de longo prazo para empresas com dezenas de servidores.

Para a maioria das PMEs, a abordagem 2 (API simples) é o ponto de equilíbrio certo. Cobre o essencial sem o overhead operacional da federação.

Integração com segurança e allowlist

O registry e a camada de segurança trabalham juntos: o registry informa o que existe e o que cada perfil pode ver; a allowlist no MCP server impõe o que cada agente pode efetivamente chamar.

O fluxo completo de uma chamada autorizada é:

Agente consulta registry → recebe lista de servidores e ferramentas disponíveis para seu perfil.
Agente decide chamar a ferramenta buscar_pedido no servidor mcp-crm.
Agente envia a chamada com o JWT no header.
Servidor MCP valida o JWT, verifica se buscar_pedido está na allowlist do agente e se o scope pedidos:leitura está presente no token.
Servidor executa a ferramenta e retorna o resultado.
Servidor registra a chamada nos logs de auditoria.

Para o checklist completo de segurança nesse fluxo, veja segurança em MCP: allowlist, sandbox, scopes e logs.

Manutenção e ciclo de vida do registry

Um registry mal mantido é pior do que nenhum registry — porque os times passam a confiar nele e ficam frustrados quando encontram informações desatualizadas.

Boas práticas de manutenção:

Dono por servidor: cada entrada no registry tem um campo contact. Essa é a pessoa responsável por manter os metadados atualizados quando o servidor mudar.
Health check automatizado: o registry faz ping periódico em cada endpoint listado. Se um servidor não responder por X minutos, o status é atualizado para inativo automaticamente.
Revisão trimestral: uma vez por trimestre, revise todas as entradas. Remova servidores que não existem mais, atualize descrições que ficaram desatualizadas.
Versionamento do schema do registry: quando você precisar mudar a estrutura do arquivo YAML/JSON (adicionar um campo novo, renomear algo), incremente o schema_version. Clientes que ainda não suportam o novo schema continuam funcionando com o comportamento anterior.

Por onde começar

Se você tem MCP servers em produção hoje sem registry, aqui está a sequência mínima:

Documente todos os servidores existentes no esquema YAML acima. Só o exercício de preencher os campos vai revelar inconsistências que você não sabia que existiam.
Suba o YAML como um endpoint HTTP estático. Já é um registry funcional.
Configure os clientes MCP para consultar esse endpoint em vez de usar configuração manual.
Nas próximas semanas, adicione filtro por tenant e health check automático.

Para entender como cada servidor deve ser estruturado como produto antes de entrar no registry, leia MCP server como produto: empacote suas ferramentas. E para o contexto geral, comece por MCP para empresas: o que é e quando implementar.