Projetando um Registro MCP Centralizado: Decisões de Arquitetura para Escala Empresarial

Modelo de dados, metadados de autenticação, descoberta dinâmica de ferramentas e isolamento multi-tenant para a camada entre seus agentes e suas ferramentas.

Quando vinte desenvolvedores mantêm seus próprios ~/.cursor/mcp.json, você não construiu uma infraestrutura MCP. Você construiu um sistema distribuído de notas adesivas que falha a cada rotação de credencial.

02:47 UTC, Terça-feira. Continental Aerospace Systems — uma fornecedora de plataforma de aviônicos com 240 engenheiros, fictícia mas infelizmente plausível — rotaciona sua chave privada do GitHub App conforme o cronograma. Às 09:00, #platform-help tem 23 tópicos de líderes de esquadrão, cada um uma variante de "MCP está quebrado no Cursor." A correção é idêntica todas as vezes — colar o novo token em ~/.cursor/mcp.json, reiniciar a IDE — mas isso precisa ser feito 187 vezes, e a equipe de plataforma perde meio dia antes de terminar.

Aquela manhã não é um problema de MCP. É um problema de registro . O protocolo funciona; o que falta é a camada entre o agente e o protocolo que sabe quais servidores existem, quem pode usar quais ferramentas e como informar a cada IDE na organização sobre uma credencial rotacionada sem 187 commits no git. Esta publicação é sobre essa camada, usando o MCP Gateway como implementação de referência ao longo de todo o texto.

1. O Problema do Desvio de Configuração: O Que 20 Desenvolvedores × 8 Servidores MCP Realmente Custam

A natureza do problema é a multiplicação. Os 240 engenheiros da Continental, distribuídos em 14 esquadrões, executam Claude Code, Cursor e VS Code contra oito servidores MCP: GitHub, Sentry, Atlassian, Linear, Slack, um servidor interno com base em Postgres fleet-telemetry server, um airworthiness-kb servidor apoiado pelas suas diretivas FAA, e Exa para pesquisa. No nível básico, cada engenheiro mantém um ~/.cursor/mcp.json assim.

~/.cursor/mcp.json — configuração MCP local, por desenvolvedor

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp",
      "headers": { "Authorization": "Bearer ghp_..." }
    },
    "sentry": {
      "url": "https://mcp.sentry.dev/mcp",
      "headers": { "Authorization": "Bearer sntrys_..." }
    },
    "linear":    { "url": "https://mcp.linear.app/mcp" },
    "atlassian": { "url": "https://mcp.atlassian.com/v1/mcp" },
    "slack":     { "url": "https://mcp.slack.com/mcp" },
    "fleet-telemetry": {
      "url": "https://fleet-mcp.internal.example/mcp",
      "headers": { "Authorization": "Bearer eyJ..." }
    },
    "airworthiness-kb": { "url": "https://kb-mcp.internal.example/mcp" },
    "exa": {
      "url": "https://mcp.exa.ai/mcp",
      "headers": { "Authorization": "Bearer exa_..." }
    }
  }
}

Oito servidores por desenvolvedor, 240 desenvolvedores, dão à equipe da plataforma cerca de 1.920 entradas de configuração implícitas para manter corretas. Os custos se dividem em cinco áreas.

A visão geral do Gateway MCP enquadra o mundo pré-registro como quatro patologias sobrepostas — infraestrutura fragmentada, proliferação de credenciais, visibilidade zero, ausência de governança:

Um registro colapsa todas as cinco linhas em uma primitiva arquitetônica: um registro de recurso por servidor MCP, de propriedade de um plano de controle, que cada IDE e cada agente referenciam por ID. O restante desta publicação descreve o que esse registro contém e o que o sistema ao seu redor precisa fazer.

2. Modelo de Dados do Registro de Servidores MCP: O Que Cada Entrada Contém

Antes da descoberta, autenticação ou isolamento, precisamos ser precisos sobre o que uma entrada de registro é. A forma que adotamos:

Entrada de registro de servidor MCP — modelo conceitual (interface TypeScript)

// Conceptual model. The on-the-wire schema is exposed through
// the TrueFoundry UI and CLI, not as a public DDL.
interface McpServerRegistryEntry {
  server_id:        string;            // stable, tenant-scoped identifier
  display_name:     string;
  transport_type:   "streamable_http" | "sse" | "stdio";

  // Connectivity (one of, by transport)
  base_url?:        string;            // remote
  command?:         string;            // stdio: e.g. "npx"
  args?:            string[];          // stdio: argv beyond command

  auth_config:      AuthConfig;                // §4
  collaborators:    Collaborator[];            // §5
  tenant_id:        string;            // always present, always filtered on
  cached_tool_schema?:   ToolSchema[];         // last successful tools/list
  cached_schema_at?:     string;
  health_status:    "healthy" | "degraded" | "unhealthy" | "circuit_open";

  created_at:       string;
  updated_at:       string;
}

Esquema conceitual — não é um DDL implantávelO plano de controle TrueFoundry expõe a forma do registro através da UI e dos manifestos YAML verificados para servidores stdio (veja a documentação do stdio). A interface acima nomeia as responsabilidades que uma entrada de registro deve cobrir; o layout de armazenamento é um detalhe de implementação.

Quatro campos realizam o trabalho estrutural. server_id + tenant_id é a chave primária pela qual tudo é filtrado. auth_config separa "onde o servidor está" de "como se comunicar com ele" — a medida que torna a rotação de credenciais barata (§4). collaborators é o ponto de anexação da política de acesso. cached_tool_schema é o que torna a descoberta dinâmica rápida o suficiente para ser utilizável.

Como são as entradas de registro da Continental

Os oito servidores da Continental tornam-se oito entradas. O interno fleet-telemetry-readonly é um streamable_http servidor usando Token Passthrough — o JWT Okta do SRE de plantão é encaminhado para o upstream, que valida a audiência e aplica segurança em nível de linha por reivindicação de equipe. Linear é registrado como um stdio servidor através de mcp-remote, com um per_user modelo de autenticação para que cada engenheiro autorize sua própria conta Linear, por a documentação do stdio-server. Os manifestos completos estão no arquivo complementar mcp-registry-manifests.yaml.

3. Descoberta Dinâmica de Ferramentas: Como os Agentes Encontram Ferramentas Com as Quais Não Foram Pré-Configurados

Uma vez que o registro é preenchido, a segunda tarefa é torná-lo consultável. O caso interessante não é um desenvolvedor no Cursor — o Cursor tem um arquivo de configuração — mas um agente autônomo, executando como um serviço, sem uma lista estática de ferramentas. O agente inicia com um token de portador; o gateway precisa transformar isso em "aqui estão as ferramentas que você, especificamente, tem permissão para usar agora," sem que o agente conheça nenhum dos servidores com antecedência.

O fluxo usa o padrão MCP tools/list método como seu ponto de entrada, mas o gateway intercepta e reescreve a resposta. O diagrama abaixo mostra a arquitetura de três planos.

Percorrendo o caminho de descoberta passo a passo:

1. O agente envia tools/list para o gateway com seu token de portador. Ele não enumera servidores; ele não tem conhecimento dos servidores.
2. O gateway executa autenticação de entrada — validar o token, resolvê-lo para um usuário, equipe ou conta virtual. O documentos de autenticação listam quatro métodos de entrada: PAT, Token de Conta Virtual, IdP JWT e TrueFoundry OAuth.
3. O gateway consulta o registro para todos os servidores no tenant do chamador onde a identidade resolvida é um colaborador. Leitura indexada.
4. Para cada servidor acessível, o gateway retorna seu cached_tool_schema quando um está atual — o caminho que é executado em estado estável — e recorre a um novo upstream tools/list apenas em caso de cache miss ou após uma listChanged invalidação (§7). Um fan-out síncrono para cada upstream em cada solicitação do chamador seria operacionalmente insustentável.
5. A lista agregada é filtrada em relação ao RBAC em nível de ferramenta. O agente de plantão da Continental é um colaborador em fleet-telemetry-readonly mas ainda tem o acesso negado a ferramentas de escrita — estas exigem uma função separada.
6. O gateway retorna um consolidado tools/list. A fiação do agente não precisa rastrear de qual servidor upstream cada ferramenta veio — embora nomes de ferramentas, descrições e mensagens de erro ainda possam indicar a origem na prática, razão pela qual os gateways frequentemente usam namespaces para nomes de ferramentas por servidor.

Duas consequências merecem ser mencionadas. Primeiro, um agente pode ser implantado em um inquilino com configuração zero específica do MCP — basta fornecer-lhe um Token de Conta Virtual, apontá-lo para o URL do gateway, e ele descobrirá o que lhe é permitido usar. O agente de resposta a incidentes de plantão da Continental é entregue como um contêiner com uma variável de ambiente. Segundo, expandir a superfície de ferramentas do agente é uma mudança no registro, não uma reimplementação do agente: adicionar airworthiness-kb à lista collaborators faz com que suas ferramentas apareçam na próxima resposta tools/list — mesmo binário, mesma configuração.

4. Armazenamento de Metadados de Autenticação: Desacoplamento de Credenciais da Configuração

A operação mais cara no mundo pré-registro é a rotação de credenciais. A mais barata no mundo pós-registro é a mesma rotação. A razão é uma escolha arquitetônica: os metadados de autenticação são armazenados na entrada do registro, não no cliente.

Os documentos de autenticação enquadram isso como uma separação entre autenticação de entrada (como o cliente prova sua identidade ao gateway) e autenticação de saída (como o gateway prova sua identidade a cada servidor downstream). De cada entrada, o auth_config controla o lado de saída:

Duas propriedades de auth_config importam operacionalmente: ele referencia credenciais, não as armazena; e é de propriedade da equipe de plataforma, não da equipe de aplicação.

A primeira propriedade é o que a integração de gerenciamento de segredos da TrueFoundry existe para organizar. As credenciais em uma entrada de registro são armazenadas como referências usando tfy-secret://<tenant>:<secret-group>:<secret-key>. O material real reside no armazenamento de segredos do inquilino — nativo do TrueFoundry, AWS SSM, GCP Secret Manager, HashiCorp Vault ou Azure Key Vault — e o gateway resolve a referência em tempo de execução. Para planos de controle auto-hospedados, o equivalente é tfy-k8s-secret://<KEY_NAME>, apoiado por um segredo do Kubernetes.

Como a rotação da Continental se deu após o registro

Mesma rotação às 02:47 UTC. O Vault insere a nova chave em tfy-secret://continental-aerospace:github-app:GITHUB_APP_PRIVATE_KEY. A próxima invocação da ferramenta GitHub desreferencia o segredo, obtém o novo valor e encaminha a solicitação. Zero alterações de configuração do desenvolvedor. Zero tickets. A equipe de plataforma fica sabendo da rotação por meio de um painel na manhã seguinte.

5. Isolamento Multi-Tenant: Arquitetura de Namespace para Registros Corporativos

Um registro que contém servidores para um único inquilino é simples. Um registro que contém servidores para centenas — ou, em um plano de controle auto-hospedado, para várias unidades de negócio dentro da mesma empresa — precisa oferecer uma garantia mais forte: os servidores da Org A devem ser invisíveis para a Org B, não meramente inalcançáveis. "Inalcançável" é um 403 que o agente errado pode ver. "Invisível" é um ferramentas/lista resposta que não sugere a existência de outro inquilino.

Inquilino na URL. A alteração de URL v0.130 moveu a URL do gateway de /api/llm/mcp/<server>/server para /api/llm/<tenant>/mcp/<server>/server. O inquilino agora faz parte do caminho endereçável — o que faz o encadeamento OAuth do MCP funcionar e o que permite que um gateway físico atenda a muitos inquilinos sem estado ambiente.

Inquilino em cada consulta. Dentro do registro, cada leitura é parametrizada por tenant_id. Não há um caminho para "listar todos os servidores"; apenas "listar todos os servidores neste inquilino." Codificar o filtro na camada de acesso a dados não elimina o vazamento entre inquilinos como uma classe de bug — cache, propagação de contexto assíncrono, workers em segundo plano, índices de pesquisa e junções de telemetria ainda podem vazar — mas remove o vetor maior e mais provável, aquele onde uma cláusula ausente de WHERE em uma verificação RBAC retorna as linhas do inquilino errado.

Inquilino na identidade. Colaboradores são resolvidos através do modelo de identidade do plano de controle. Usuários pertencem a inquilinos; equipes são delimitadas a inquilinos; contas virtuais são criadas dentro de inquilinos. A primeira verificação do motor RBAC é que o inquilino do chamador corresponde ao inquilino do recurso.

Caminho de consulta conceitual — o filtro de tenant é inegociável

// Tenant filter applied before the access-policy check.
// This shrinks the blast radius of an RBAC bug — the wrong tenant's
// rows aren't loaded — but caching, async context, and indexers
// still need their own tenant-scoping discipline.
function listAccessibleServers(caller: Identity): McpServerRegistryEntry[] {
  const rows = registry.query({
    tenant_id: caller.tenant_id,
    health_status: { $ne: "circuit_open" },
  });
  return rows.filter(server => rbac.canRead(caller, server));
}

Serviços compartilhados entre unidades de negócio na Continental

As divisões de aviônicos e sistemas terrestres da Continental operam como tenants separados no mesmo plano de controle. Na maioria das vezes, isso está perfeitamente correto — o servidor de telemetria da frota não é relevante, e não é legalmente apropriado, para engenheiros de sistemas terrestres visualizarem. Mas um servidor, um MCP de documentação empresarial, deve ser visível para ambos. O padrão é uma concessão explícita de colaborador entre tenants: a entrada tenant_id permanece no tenant proprietário, mas a collaborators lista inclui um principal do outro. A visibilidade compartilhada é uma concessão deliberada e auditada — nunca um acidente.

6. Fluxos de Registro Público vs. Auto-hospedado

Registrar um servidor MCP público e registrar um auto-hospedado são a mesma operação conceitual — produzir uma entrada de registro — mas os fluxos de trabalho parecem diferentes, e o registro deve suportar ambos.

Para servidores públicos (GitHub, Linear, Sentry, Atlassian, Slack, Exa, Playwright MCP, DeepWiki, Context7), a operação se resume a alguns cliques. O fluxo "Adicionar Servidor MCP" do MCP Gateway expõe cinco caminhos de registro: Conectar Servidores MCP Remotos Oficiais, Conectar qualquer Servidor MCP Remoto, Criar um Servidor MCP Virtual, Importar de Especificação OpenAPI, e Servidor MCP Baseado em Stdio Hospedado. O primeiro seleciona de um catálogo curado com metadados de autenticação pré-preenchidos; você fornece o ID/segredo do cliente OAuth e o restante da entrada é gerado.

Servidores auto-hospedados — os internos da Continental fleet-telemetry-readonly, por exemplo — usam Conectar qualquer Servidor MCP Remoto (para endpoints HTTPS) ou Servidor MCP Hospedado Baseado em Stdio (para servidores estilo CLI). O caminho stdio é interessante porque o gateway se torna responsável por executar o processo, não apenas por chamá-lo. A documentação do stdio define a forma verificada do manifesto YAML: command, args, e um auth_data bloco com auth_level: per_user (o segredo de cada chamador substituído em {{API_KEY}}) ou auth_level: global (um valor compartilhado em todo o inquilino). O companheiro mcp-registry-manifests.yaml inclui quatro exemplos práticos que cobrem ambos os níveis de autenticação e o padrão de Servidor MCP Virtual.

Independentemente do caminho, o registro valida que um servidor recém-registrado está acessível antes de publicá-lo. Para servidores HTTPS remotos, isso é uma sondagem tools/list. Para stdio, o gateway inicializa um processo de curta duração, envia initialize, e garante que o servidor responda corretamente. Um servidor que não pode ser sondado é rejeitado no registro — não é adicionado em um estado quebrado que se manifesta como 503s quando os desenvolvedores tentam usá-lo.

7. Versionamento do Esquema de Ferramentas e Invalidação de Cache

Armazenar em cache o esquema da ferramenta é a diferença entre um registro utilizável e um inutilizável. Uma implementação ingênua que chama tools/list contra cada servidor upstream em cada solicitação do agente multiplica a latência do gateway pelo número de upstreams e adiciona um modo de falha por servidor. O cache resolve o problema de latência e cria um novo: o desvio de esquema.

O gateway mantém um cached_tool_schema por entrada, atualizado de duas maneiras.

Atualização orientada por eventos. A especificação MCP define uma listChanged notificação que os servidores que declaram { "tools": { "listChanged": true } } podem emitir quando a lista de ferramentas é alterada. Para servidores que declaram a capacidade e emitem de forma confiável em sua conexão persistente, o gateway trata a notificação como um sinal de invalidação e busca dados novos antes que o próximo chamador veja dados desatualizados. Esta é a via rápida quando disponível — mas não é universal: muitos servidores MCP não implementam listChanged de forma alguma, e alguns declaram a capacidade, mas emitem de forma inconsistente entre os transportes.

Atualização periódica. Para todo o resto, o gateway re-sonda em uma cadência ajustável (poucos minutos para servidores ativos, mais longa para os conhecidos como inativos). A sonda reutiliza o pool de conexões existente. Na prática, a maioria das implantações de produção depende da atualização periódica como mecanismo principal e tratam listChanged como oportunista quando funciona.

8. Verificação de Integridade e Disjuntor para Servidores MCP

O registro precisa saber o que está ativo. Caso contrário, ele faz a pior coisa: anuncia uma ferramenta cujo servidor está retornando 503 há uma hora, e cada agente no inquilino esgota o tempo limite ao tentar chamá-lo.

O subsistema de integridade executa três ciclos.

Sonda. Um worker em segundo plano chama tools/list em cada servidor em uma cadência ajustável. Em caso de sucesso, o servidor é promovido a íntegro e atualiza o esquema em cache; falha (erro de rede, 5xx, payload malformado) incrementa um contador.

Limiar. Assim que o contador ultrapassa um limiar — ajustado por classe de servidor, já que SaaS público tem mais tolerância do que interno — o servidor transita para não íntegro e suas ferramentas são sinalizadas. Após um segundo limite, o disjuntor abre (circuit_open). A maioria das implementações opta por ocultar um servidor com circuito aberto das tools/list respostas inteiramente, para que os agentes vejam uma lista de ferramentas menor, em vez de uma com entradas com falha; alguns mantêm as ferramentas visíveis, mas as marcam, na teoria de que os planejadores de agentes podem se adaptar melhor a "indisponível" do que a "ausente". A decisão correta depende de como seus agentes lidam com a ausência.

Recuperação. O disjuntor fica semiaberto após um período de resfriamento: uma sondagem; em caso de sucesso, fechado; em caso de falha, o período de resfriamento dobra. Prática padrão de retirada exponencial.

A razão pela qual isso importa não é a latência — é a composição da confiabilidade. Sem o disjuntor, um agente que depende de sete servidores upstream falha quando qualquer um deles falha. Com ele, o agente perde as ferramentas de um servidor e continua com os outros seis. Para o agente de resposta a incidentes de plantão da Continental, essa é a diferença entre "continuamos a triar enquanto o Sentry está inativo" e "o próprio assistente de IA está inativo porque o Sentry está inativo".

Configuração distribuída vs. registro centralizado

As diferenças se manifestam em seis dimensões.

Continental, antes e depois

9. Perguntas Frequentes

O registro precisa estar no mesmo plano de controle que o restante da nossa infraestrutura de IA?

Não precisa , mas a colocalização com o gateway do modelo rende dividendos compostos — o mesmo mecanismo RBAC, integração com gerenciador de segredos, pipeline de auditoria e modelo de identidade atendem tanto ao tráfego do modelo quanto ao tráfego de ferramentas. O TrueFoundry MCP Gateway é intencionalmente parte do mesmo plano de controle que o AI Gateway por essa razão.

O que acontece quando a configuração local do IDE de um desenvolvedor entra em conflito com o registro?

Não acontece, porque a configuração do IDE não contém mais credenciais — apenas uma URL de gateway. Após a v0.130, a configuração do Cursor ou VS Code para um servidor MCP se resume a uma URL de gateway com escopo de locatário, mais qualquer bootstrap OAuth ou IdP que sua organização já exija — o gateway lida com a resolução de credenciais do outro lado. Não há segredo por servidor na configuração do IDE para divergir do registro.

Como o registro lida com servidores com autenticação personalizada ou não padrão?

Por meio do Encaminhamento de Tokens. O cliente define x-tfy-mcp-headers com qualquer autenticação que o upstream exija, e o gateway a encaminha. Este é o mecanismo de escape para servidores cujos esquemas não correspondem a nenhum modelo integrado — comum para serviços internos legados.

Podemos expor apenas um subconjunto de ferramentas de um servidor registrado?

Sim, por meio de um Servidor MCP Virtual. O recurso de servidor virtual monta um pacote selecionado de ferramentas extraídas de um ou mais servidores registrados e concede acesso a esse pacote de forma independente. O kit de ferramentas de resposta a incidentes da Continental é um servidor virtual que expõe ferramentas Sentry somente leitura, além de ferramentas de telemetria de frota somente leitura, para a equipe de plantão — nenhuma das operações destrutivas é acessível.

E se um servidor MCP upstream mudar seu transporte de HTTP streamable para SSE?

O gateway segue o servidor. A partir da v0.130, ele preserva o transporte do upstream em vez de normalizar para HTTP streamable. Clientes que seguem o padrão da especificação de HTTP streamable primeiro e depois fallback para SSE continuam funcionando sem alterações de configuração.

Como o registro interage com agentes autônomos que precisam descobrir ferramentas em tempo de execução?

Esse é o objetivo do §3. Um agente se autentica uma vez no gateway, chama tools/list, e recebe uma lista de ferramentas selecionada e filtrada por RBAC. Ele pode então chamar tools/call com qualquer item dessa lista. Sem inventário pré-definido, sem novas implantações.

Qual é a maneira mais simples de começar?

Registre um servidor que você já usa — Linear, GitHub ou Sentry são as escolhas iniciais usuais porque os fluxos de autenticação são bem estabelecidos — e aponte a configuração do IDE de uma equipe para a URL do gateway. Não tente migrar 240 desenvolvedores e 8 servidores de uma só vez; migre um servidor e 10 desenvolvedores, aprenda com a implementação e depois expanda.

Dê o próximo passo

Se ~/.cursor/mcp.json o desvio começou a custar tempo à sua equipa de plataforma, esse é o sinal para centralizar. O TrueFoundry MCP Gateway é a camada de registo e política que construímos para essa transição; pode ler a documentação da arquitetura ou experimentá-lo gratuitamente.

Leitura adicional

• TrueFoundry MCP Gateway — visão geral · registo centralizado, enquadramento antes e depois
• MCP Gateway — autenticação e segurança · autenticação de entrada vs. saída, todos os sete modelos de saída
• MCP Gateway — primeiros passos · os cinco caminhos de registo e o modelo de colaborador/função
• Servidor MCP baseado em stdio hospedado · formato de manifesto YAML verificado, autenticação baseada em variáveis de ambiente
• Servidor MCP Virtual · pacotes de ferramentas selecionados sem necessidade de reimplementação
• Usar o Secret Manager em Integrações · o tfy-secret:// formato de referência
• v0.130 Mudanças de URL e transporte · tenant-in-URL, encadeamento OAuth, fallback SSE
• Especificação MCP — ferramentas · tools/list, tools/call, listChanged notificação
• Segurança empresarial Claude — MCP Gateway com allowlisting · padrão para implementação empresarial governada

‍

‍