Diseño de un registro MCP centralizado: Decisiones de arquitectura para escala empresarial

Modelo de datos, metadatos de autenticación, descubrimiento dinámico de herramientas y aislamiento multitenencia para la capa entre sus agentes y sus herramientas.

Cuando veinte desarrolladores mantienen su propio ~/.cursor/mcp.json, no han construido una infraestructura MCP. Han construido un sistema distribuido de notas adhesivas que falla de forma segura cada vez que una credencial rota.

02:47 UTC, martes. Continental Aerospace Systems —un proveedor de plataformas de aviónica de 240 ingenieros, ficticio pero lamentablemente plausible— rota su clave privada de la aplicación GitHub según lo programado. Para las 09:00, #platform-help tiene 23 hilos de los líderes de equipo, cada uno una variante de "MCP está roto en Cursor". La solución es idéntica cada vez —pegar el nuevo token en ~/.cursor/mcp.json, reiniciar el IDE— pero hay que hacerlo 187 veces, y el equipo de plataforma pierde medio día antes de terminar.

Esa mañana no es un problema de MCP. Es un problema de registro . El protocolo funciona; lo que falta es la capa entre el agente y el protocolo que sabe qué servidores existen, quién puede usar qué herramientas y cómo informar a cada IDE de la organización sobre una credencial rotada sin 187 commits de git. Esta publicación trata sobre esa capa, utilizando el MCP Gateway de TrueFoundry como implementación de referencia en todo el texto.

1. El problema de la desviación de la configuración: Lo que realmente cuestan 20 desarrolladores × 8 servidores MCP

La magnitud del problema es la multiplicación. Los 240 ingenieros de Continental, distribuidos en 14 equipos, ejecutan Claude Code, Cursor y VS Code contra ocho servidores MCP: GitHub, Sentry, Atlassian, Linear, Slack, un servidor interno respaldado por Postgres de fleet-telemetry , un airworthiness-kb servidor respaldado por sus directivas de la FAA, y Exa para búsquedas. De base, cada ingeniero mantiene un ~/.cursor/mcp.json como este.

~/.cursor/mcp.json — configuración local de MCP, por desarrollador

{
  "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_..." }
    }
  }
}

Ocho servidores por desarrollador, 240 desarrolladores, le da al equipo de plataforma unas 1.920 entradas de configuración implícitas que mantener correctas. Los costos se distribuyen en cinco áreas.

Resumen de la pasarela MCP enmarca el mundo anterior al registro como cuatro patologías superpuestas: infraestructura fragmentada, dispersión de credenciales, visibilidad nula y falta de gobernanza:

Un registro consolida las cinco filas en una primitiva arquitectónica: un registro de recursos por servidor MCP, propiedad de un plano de control, al que cada IDE y cada agente hacen referencia por ID. El resto de esta publicación trata sobre lo que contiene ese registro y lo que el sistema que lo rodea debe hacer.

2. Modelo de datos del registro de servidores MCP: Qué contiene cada entrada

Antes del descubrimiento, la autenticación o el aislamiento, debemos ser precisos sobre lo que una entrada de registro es. La forma en la que convergimos:

Entrada del registro de servidores MCP — modelo conceptual (interfaz 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 conceptual — no es un DDL desplegableEl plano de control de TrueFoundry expone la forma del registro a través de la interfaz de usuario y los manifiestos YAML verificados para los servidores stdio (véase la documentación de stdio). La interfaz anterior nombra las responsabilidades que debe cubrir una entrada de registro; el diseño del almacenamiento es un detalle de implementación.

Cuatro campos realizan el trabajo estructural. server_id + tenant_id es la clave primaria sobre la que todo se filtra. auth_config separa "dónde está el servidor" de "cómo comunicarse con él", la medida que abarata la rotación de credenciales (§4). collaborators es el punto de conexión de la política de acceso. cached_tool_schema es lo que hace que el descubrimiento dinámico sea lo suficientemente rápido como para ser utilizable.

Aspecto de las entradas de registro de Continental

Los ocho servidores de Continental se convierten en ocho entradas. El interno fleet-telemetry-readonly es un streamable_http servidor que utiliza Token Passthrough: el JWT de Okta del SRE de guardia se reenvía al sistema superior, que valida la audiencia y aplica seguridad a nivel de fila por reclamación de equipo. Linear está registrado como un stdio servidor a través de mcp-remote, con un per_user modelo de autenticación para que cada ingeniero autorice su propia cuenta de Linear, por la documentación de stdio-server. Los manifiestos completos se encuentran en el archivo complementario mcp-registry-manifests.yaml.

3. Descubrimiento Dinámico de Herramientas: Cómo los Agentes Encuentran Herramientas con las que No Estaban Preconfigurados

Una vez que el registro está poblado, la segunda tarea es hacerlo consultable. El caso interesante no es el de un desarrollador en Cursor —Cursor tiene un archivo de configuración— sino el de un agente autónomo, ejecutándose como un servicio, sin una lista estática de herramientas. El agente se activa con un token de portador; el gateway tiene que convertir eso en "aquí están las herramientas que tú, específicamente, tienes permitido usar ahora mismo," sin que el agente conozca ninguno de los servidores de antemano.

El flujo utiliza el método estándar MCP tools/list método como su punto de entrada, pero el gateway intercepta y reescribe la respuesta. El siguiente diagrama muestra la arquitectura de tres planos.

Recorriendo la ruta de descubrimiento paso a paso:

1. El agente envía tools/list al gateway con su token de portador. No enumera servidores; no conoce los servidores.
2. El gateway ejecuta autenticación de entrada — valida el token, lo resuelve a un usuario, equipo o cuenta virtual. La documentación de autenticación enumera cuatro métodos de entrada: PAT, Virtual Account Token, IdP JWT y TrueFoundry OAuth.
3. La pasarela consulta el registro para todos los servidores en el inquilino del llamador donde la identidad resuelta es un colaborador. Lectura indexada.
4. Para cada servidor accesible, la pasarela devuelve su cached_tool_schema cuando hay uno actual —la ruta que se ejecuta en estado estable— y recurre a un upstream nuevo tools/list solo en caso de fallo de caché o después de una listChanged invalidación (§7). La distribución sincrónica a cada upstream en cada solicitud del llamador sería operacionalmente insostenible.
5. La lista agregada se filtra según el RBAC a nivel de herramienta. El agente de guardia de Continental es un colaborador en fleet-telemetry-readonly pero aún se le deniegan las herramientas de escritura; esas requieren un rol separado.
6. La pasarela devuelve una consolidada tools/list. El cableado del agente no tiene que rastrear de qué servidor upstream provino cada herramienta —aunque los nombres de las herramientas, las descripciones y los mensajes de error aún pueden delatar el origen en la práctica, razón por la cual las pasarelas a menudo asignan un espacio de nombres a los nombres de las herramientas por servidor.

Cabe mencionar dos consecuencias. Primero, un agente puede implementarse en un inquilino sin ninguna configuración específica de MCP: se le proporciona un Token de Cuenta Virtual, se le apunta a la URL de la pasarela y descubre lo que se le permite usar. El agente de respuesta a incidentes de guardia de Continental se entrega como un contenedor con una variable de entorno. Segundo, ampliar la superficie de herramientas del agente es un cambio en el registro, no una reimplementación del agente: añadir airworthiness-kb a la collaborators lista hace que sus herramientas aparezcan en la siguiente tools/list respuesta — el mismo binario, la misma configuración.

4. Almacenamiento de metadatos de autenticación: Desacoplamiento de credenciales de la configuración

La operación más costosa en el mundo anterior al registro es la rotación de credenciales. La más barata en el mundo posterior al registro es la misma rotación. La razón es una elección arquitectónica: los metadatos de autenticación se almacenan en la entrada del registro, no en el cliente.

Los documentos de autenticación lo enmarcan como una separación entre la autenticación de entrada (cómo el cliente demuestra su identidad a la pasarela) y la autenticación de salida (cómo la pasarela demuestra su identidad a cada servidor descendente). La auth_config de cada entrada auth_config controla el lado de salida:

Dos propiedades de auth_config son importantes operativamente: hace referencia a credenciales, no las almacena; y es propiedad del equipo de plataforma, no del equipo de aplicación.

La primera propiedad es lo que la integración de TrueFoundry con el gestor de secretos existe para simplificar. Las credenciales en una entrada de registro se almacenan como referencias utilizando tfy-secret://<tenant>:<secret-group>:<secret-key>. El material real reside en el almacén de secretos del inquilino —nativo de TrueFoundry, AWS SSM, GCP Secret Manager, HashiCorp Vault o Azure Key Vault— y la pasarela resuelve la referencia en tiempo de ejecución. Para planos de control autoalojados, el equivalente es tfy-k8s-secret://<KEY_NAME>, respaldado por un secreto de Kubernetes.

Cómo fue la rotación de Continental después del registro

Misma rotación a las 02:47 UTC. Vault deposita la nueva clave en tfy-secret://continental-aerospace:github-app:GITHUB_APP_PRIVATE_KEY. La siguiente invocación de la herramienta de GitHub desreferencia el secreto, obtiene el nuevo valor y reenvía la solicitud. Cero cambios de configuración para el desarrollador. Cero tickets. El equipo de plataforma se entera de la rotación a través de un panel de control a la mañana siguiente.

5. Aislamiento multi-inquilino: Arquitectura de espacios de nombres para registros empresariales

Un registro que aloja servidores para un solo inquilino es sencillo. Un registro que aloja servidores para cientos —o, en un plano de control autoalojado, para varias unidades de negocio dentro de la misma empresa— debe ofrecer una garantía más sólida: los servidores de la Org A deben ser invisibles para la Org B, no meramente inalcanzables. "Inalcanzable" es un 403 que un agente equivocado podría ver. "Invisible" es una herramientas/lista respuesta que no insinúe la existencia de otro inquilino.

Inquilino en la URL. El cambio de URL v0.130 movió la URL de la pasarela de /api/llm/mcp/<server>/server a /api/llm/<tenant>/mcp/<server>/server. El inquilino ahora forma parte de la ruta direccionable, lo que permite que el encadenamiento de OAuth de MCP funcione y que una única pasarela física sirva a muchos inquilinos sin estado ambiental.

Inquilino en cada consulta. Dentro del registro, cada lectura se parametriza por tenant_id. No existe una ruta para "listar todos los servidores"; solo "listar todos los servidores en este inquilino". Codificar el filtro directamente en la capa de acceso a datos no elimina las fugas entre inquilinos como una clase de error —el almacenamiento en caché, la propagación de contexto asíncrona, los procesos en segundo plano, los índices de búsqueda y las uniones de telemetría aún pueden filtrar información—, pero elimina el vector más grande y probable, aquel en el que una cláusula WHERE faltante en una comprobación de RBAC devuelve filas del inquilino incorrecto.

Inquilino en la identidad. Los colaboradores se resuelven a través del modelo de identidad del plano de control. Los usuarios pertenecen a inquilinos; los equipos están limitados a inquilinos; las cuentas virtuales se crean dentro de inquilinos. La primera comprobación del motor RBAC es que el inquilino del llamante coincida con el inquilino del recurso.

Ruta de consulta conceptual — el filtro de inquilino no es negociable

// 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));
}

Servicios compartidos entre unidades de negocio en Continental

Las divisiones de aviónica y sistemas terrestres de Continental funcionan como inquilinos separados en el mismo plano de control. La mayor parte del tiempo, esto es exactamente correcto: el servidor de telemetría de la flota no es relevante, y no es legalmente apropiado, para que lo vean los ingenieros de sistemas terrestres. Pero un servidor, un MCP de documentación empresarial, debería ser visible para ambos. El patrón es una concesión explícita de colaborador entre inquilinos: el tenant_id de la entrada permanece en el inquilino propietario, pero la lista de collaborators incluye un principal del otro. La visibilidad compartida es una concesión deliberada y auditada, nunca un accidente.

6. Flujos de registro públicos vs. autoalojados

Registrar un servidor MCP público y registrar uno autoalojado son la misma operación conceptual —producir una entrada de registro—, pero los flujos de trabajo son diferentes y el registro debe soportar ambos.

Para servidores públicos (GitHub, Linear, Sentry, Atlassian, Slack, Exa, Playwright MCP, DeepWiki, Context7), la operación se reduce a unos pocos clics. El flujo "Añadir servidor MCP" de la pasarela MCP expone cinco rutas de registro: Conectar servidores MCP remotos oficiales, Conectar cualquier servidor MCP remoto, Crear un servidor MCP virtual, Importar desde especificación OpenAPI, y Servidor MCP alojado basado en Stdio. El primero selecciona de un catálogo curado con metadatos de autenticación precargados; usted proporciona el ID/secreto de cliente OAuth y el resto de la entrada se genera.

Servidores autoalojados — los internos de Continental, fleet-telemetry-readonly, por ejemplo — utilizan Conectar cualquier servidor MCP remoto (para puntos finales HTTPS) o Servidor MCP alojado basado en Stdio (para servidores de estilo CLI). La ruta stdio es interesante porque la pasarela se encarga de ejecutar el proceso, no solo de invocarlo. La documentación de stdio define la estructura verificada del manifiesto YAML: comando, argumentos, y un datos de autenticación bloque con nivel_autenticación: por_usuario (el secreto de cada invocador se sustituye en {{API_KEY}}) o nivel_autenticación: global (un valor compartido en todo el inquilino). La guía complementaria mcp-registry-manifests.yaml incluye cuatro ejemplos prácticos que cubren ambos niveles de autenticación y el patrón de servidor MCP virtual.

Independientemente de la ruta, el registro valida que un servidor recién registrado sea accesible antes de publicarlo. Para los servidores HTTPS remotos, se realiza una prueba tools/list. Para stdio, la pasarela inicia un proceso de corta duración, envía initialize, y se asegura de que el servidor responda correctamente. Un servidor que no puede ser sondeado es rechazado en el registro — no se añade en un estado defectuoso que se manifieste como errores 503 una vez que los desarrolladores intenten usarlo.

7. Versionado del esquema de herramientas e invalidación de la caché

El almacenamiento en caché del esquema de herramientas es la diferencia entre un registro utilizable y uno inutilizable. Una implementación ingenua que llama a tools/list a cada servidor ascendente en cada solicitud del agente multiplica la latencia de la pasarela por el número de servidores ascendentes y añade un modo de fallo por servidor. La caché resuelve el problema de la latencia y crea uno nuevo: la deriva del esquema.

La pasarela mantiene un cached_tool_schema por entrada, que se actualiza de dos formas.

Actualización basada en eventos. La especificación MCP define una listChanged notificación que los servidores que declaran { "tools": { "listChanged": true } } pueden emitir cuando su lista de herramientas cambia. Para los servidores que declaran la capacidad y emiten de forma fiable en su conexión persistente, la pasarela trata la notificación como una señal de invalidación y obtiene datos actualizados antes de que el siguiente solicitante vea datos obsoletos. Esta es la vía rápida cuando está disponible, pero no es universal: muchos servidores MCP no implementan listChanged en absoluto, y algunos declaran la capacidad pero emiten de forma inconsistente a través de los transportes.

Actualización periódica. Para todo lo demás, la pasarela vuelve a sondear con una cadencia configurable (pocos minutos para servidores activos, más larga para los que se sabe que están inactivos). El sondeo reutiliza el pool de conexiones existente. En la práctica, la mayoría de las implementaciones de producción se apoyan en la actualización periódica como mecanismo principal y tratan listChanged como algo oportunista cuando funciona.

8. Comprobación de estado e interrupción de circuito para servidores MCP

El registro debe saber qué está activo. De lo contrario, hace lo peor: anuncia una herramienta cuyo servidor ha estado devolviendo errores 503 durante una hora, y cada agente en el inquilino agota el tiempo de espera al intentar llamarla.

El subsistema de salud ejecuta tres bucles.

Sondeo. Un proceso en segundo plano invoca tools/list en cada servidor con una cadencia configurable. El éxito promueve el servidor a saludable y actualiza el esquema en caché; el fallo (error de red, 5xx, carga útil mal formada) incrementa un contador.

Umbral. Una vez que el contador supera un umbral —ajustado por clase de servidor, ya que el SaaS público tiene más margen que el interno— el servidor pasa a no saludable y sus herramientas se marcan. Después de un segundo umbral, el disyuntor se abre (circuit_open). La mayoría de las implementaciones optan por suprimir un servidor con circuito abierto de las respuestas de tools/list por completo, de modo que los agentes vean una lista de herramientas más pequeña en lugar de una con entradas defectuosas; algunos mantienen las herramientas visibles pero las marcan, bajo la idea de que los planificadores de agentes pueden adaptarse mejor a "no disponible" que a "faltante". La mejor opción depende de cómo sus agentes gestionen la ausencia.

Recuperación. El disyuntor está semiabierto después de un período de enfriamiento: una prueba; si tiene éxito, se cierra; si falla, el período de enfriamiento se duplica. Prácticas estándar de retroceso exponencial.

La razón por la que esto importa no es la latencia, sino la composición de la fiabilidad. Sin la interrupción del circuito, un agente que depende de siete servidores de origen falla cuando cualquiera de ellos falla. Con ella, el agente pierde las herramientas de un servidor y continúa con los otros seis. Para el agente de respuesta a incidentes de guardia de Continental, esa es la diferencia entre "seguimos clasificando mientras Sentry está caído" y "el asistente de IA está caído porque Sentry está caído".

Configuración distribuida vs. registro centralizado

Las diferencias se resumen en seis dimensiones.

Continental, antes y después

9. Preguntas frecuentes

¿Tiene que residir el registro en el mismo plano de control que el resto de nuestra infraestructura de IA?

No tiene que, pero la coubicación con la pasarela de modelos rinde dividendos compuestos: el mismo motor RBAC, la integración con el gestor de secretos, el pipeline de auditoría y el modelo de identidad sirven tanto para el tráfico de modelos como para el tráfico de herramientas. La pasarela MCP de TrueFoundry forma parte intencionadamente del mismo plano de control que la pasarela de IA por esta razón.

¿Qué sucede cuando la configuración local del IDE de un desarrollador entra en conflicto con el registro?

No lo hace, porque la configuración del IDE ya no contiene credenciales, solo una URL de pasarela. Después de la v0.130, la configuración de Cursor o VS Code para un servidor MCP se reduce a una URL de pasarela con ámbito de inquilino más cualquier arranque de OAuth o IdP que su organización ya requiera; la pasarela gestiona la resolución de credenciales en el otro lado. No hay ningún secreto por servidor en la configuración del IDE que pueda desviarse del registro.

¿Cómo gestiona el registro los servidores con autenticación personalizada o no estándar?

Mediante el reenvío de tokens. El cliente establece x-tfy-mcp-headers con la autenticación que el origen requiera, y el gateway la reenvía. Este es el mecanismo de escape para servidores cuyos esquemas no coinciden con ningún modelo integrado, algo común en servicios internos heredados.

¿Podemos exponer solo un subconjunto de herramientas de un servidor registrado?

Sí, a través de un Servidor MCP Virtual. La función de servidor virtual ensambla un paquete de herramientas seleccionado, extraído de uno o más servidores registrados, y concede acceso a ese paquete de forma independiente. El kit de herramientas de respuesta a incidentes de Continental es un servidor virtual que expone herramientas de Sentry de solo lectura, además de herramientas de telemetría de flota de solo lectura, al equipo de guardia; ninguna de las operaciones destructivas es accesible.

¿Qué ocurre si un servidor MCP de origen cambia su transporte de HTTP en streaming a SSE?

El gateway sigue al servidor. A partir de la v0.130, conserva el transporte del origen en lugar de normalizarlo a HTTP en streaming. Los clientes que siguen el patrón de la especificación de HTTP en streaming primero y luego SSE como alternativa, siguen funcionando sin cambios en la configuración.

¿Cómo interactúa el registro con los agentes autónomos que necesitan descubrir herramientas en tiempo de ejecución?

Ese es el objetivo del §3. Un agente se autentica una vez en el gateway, llama a tools/list, y recibe una lista de herramientas seleccionada y filtrada por RBAC. Luego puede llamar a tools/call con cualquier elemento de esa lista. Sin inventario preestablecido, sin nuevas implementaciones.

¿Cuál es la forma más sencilla de empezar?

Registra un servidor que ya utilices —Linear, GitHub o Sentry suelen ser las primeras opciones porque los flujos de autenticación están bien establecidos— y apunta la configuración del IDE de un equipo a la URL del gateway. No intentes migrar 240 desarrolladores y 8 servidores de una sola vez; migra un servidor y 10 desarrolladores, aprende del despliegue y luego expande.

Da el siguiente paso

Si ~/.cursor/mcp.json la deriva ha empezado a costar tiempo a tu equipo de plataforma, esa es la señal para centralizar. El TrueFoundry MCP Gateway es la capa de registro y políticas que construimos para esa transición; puedes leer la documentación de la arquitectura o probarlo gratis.

Lectura adicional

• TrueFoundry MCP Gateway — resumen · registro centralizado, enfoque antes y después
• MCP Gateway — autenticación y seguridad · autenticación entrante vs. saliente, los siete modelos salientes
• MCP Gateway — primeros pasos · las cinco rutas de registro y el modelo de colaborador/rol
• Servidor MCP alojado basado en stdio · estructura de manifiesto YAML verificada, autenticación basada en entorno
• Servidor MCP virtual · paquetes de herramientas seleccionados sin redespliegue
• Usar Secret Manager en las integraciones · el tfy-secret:// formato de referencia
• v0.130 Cambios en URL y transporte · inquilino-en-URL, encadenamiento OAuth, respaldo SSE
• Especificación MCP — herramientas · tools/list, tools/call, listChanged notificación
• Seguridad empresarial de Claude — Pasarela MCP con lista de permitidos · patrón para el despliegue empresarial gobernado

‍

‍