Phase 19 - Lesson 13

Capstone 13 — Servidor MCP con Registro y Gobernanza

El Model Context Protocol dejó de ser el futuro para convertirse en la especificación de uso de herramientas predeterminada en 2026. Anthropic, OpenAI, Google y todos los IDE principales incorporan clientes MCP. Pinterest publicó su ecosistema interno de servidores MCP. El AAIF Registry formalizó los metadatos de capacidades en la ruta .well-known. AWS ECS publicó el despliegue de referencia sin estado (stateless). El goose-agent de Block incorporó el mismo protocolo dentro de un asistente alojado. El diseño de producción de 2026 consiste en: transporte StreamableHTTP, alcances (scopes) OAuth 2.1, control de directivas por OPA y un registro que permite a los equipos de plataforma descubrir, validar y habilitar servidores. Desarrolle eso de extremo a extremo.

Type: Capstone Languages: Python (servidor, vía FastMCP) o TypeScript (@modelcontextprotocol/sdk), Go (servicio de registro) Prerequisites: Phase 11 (LLM engineering), Phase 13 (tools and MCP), Phase 14 (agents), Phase 17 (infrastructure), Phase 18 (safety) Phases exercised: P11 · P13 · P14 · P17 · P18 Time: 25 horas

Problem

MCP se convirtió en la lengua franca del uso de herramientas. Claude Code, Cursor 3, Amp, OpenCode, Gemini CLI y cada agente administrado consumen ahora servidores MCP. Los desafíos en producción no radican en el desarrollo de los servidores (FastMCP facilita mucho esto), sino en desplegarlos a escala con requisitos empresariales: alcances OAuth por cliente (tenant), políticas OPA en herramientas destructivas, escalado horizontal stateless mediante StreamableHTTP, un registro para descubrimiento y logs de auditoría por llamada de herramienta. El ecosistema MCP interno de Pinterest y la especificación de AAIF Registry establecen el estándar para 2026.

Construirá un servidor MCP que expone 10 herramientas internas (Postgres de solo lectura, listado de S3, Jira, Linear, Datadog, etc.), una UI de registro para el descubrimiento de la plataforma y un filtro de aprobación humana para herramientas destructivas. La prueba de carga demostrará el escalado horizontal de StreamableHTTP. El registro de auditoría cumplirá con los requisitos de una revisión de seguridad empresarial.

Concept

La revisión de MCP de 2026 exige StreamableHTTP como el transporte predeterminado. A diferencia del diseño anterior basado en stdio y SSE, StreamableHTTP es sin estado por defecto: un único endpoint HTTP acepta solicitudes JSON-RPC, transmite respuestas (streams) y admite conexiones de larga duración para notificaciones. Ser stateless permite el escalado horizontal detrás de un balanceador de carga.

La autorización se maneja mediante OAuth 2.1 con alcances por herramienta. Un token porta alcances como jira:read, s3:list, postgres:query:readonly. El servidor MCP valida los alcances en el momento en que se llama a la herramienta, no solo al inicio de la sesión. Para herramientas de alto riesgo, el servidor rechaza cualquier llamada cuyo alcance no haya sido elevado a approved:by:human en los últimos N minutos; esa elevación proviene de una tarjeta de revisión de Slack.

El registro es un servicio independiente. Cada servidor MCP expone un documento .well-known/mcp-capabilities que incluye el manifiesto de sus herramientas, la URL de transporte y los requisitos de autenticación. El registro realiza varreduras periódicas (polling), valida e indexa. Los equipos de plataforma usan la UI del registro para ver qué herramientas están disponibles, qué alcances requieren y qué equipos son dueños de ellas.

Architecture

cliente MCP (Claude Code, Cursor 3, ...)
          |
          v
StreamableHTTP sobre HTTPS (JSON-RPC + streaming)
          |
          v
servidor MCP (FastMCP) detrás de balanceador de carga
          |
   +------+------+---------+----------+------------+
   v             v         v          v            v
Postgres    listado S3  Jira       Linear     Datadog
(solo       (paginado)  (lectura)  (lectura)  (consulta)
lectura)
          |
   +------+-------------+
   v                    v
barrera política OPA   herramienta destructiva MCP (servidor separado)
                        |
                        v
                   aprobación humana vía Slack
                        |
                        v
                   log de auditoria (append-only, por tenant)

  servicio de registro
     |
     v  GET /.well-known/mcp-capabilities de cada servidor
     v
     UI: buscar / validar / activar-desactivar / propiedad (ownership)

Stack

• Framework de servidor: FastMCP (Python) o @modelcontextprotocol/sdk (TypeScript)
• Transporte: StreamableHTTP sobre HTTPS (stateless)
• Autenticación: OAuth 2.1 con identidad de carga de trabajo (workload identity) vía SPIFFE / SPIRE
• Directiva: Reglas OPA / Rego por herramienta; servicio de decisión de directiva por solicitud
• Registro: autohospedado, consume manifiestos .well-known/mcp-capabilities
• Aprobación humana: Mensaje interactivo de Slack para herramientas destructivas
• Despliegue: AWS ECS Fargate o Fly.io, un servidor por tenant o compartido con alcance de tenant
• Auditoría: bucket estructurado JSONL por tenant con linaje por llamada

Build It

1. Superficie de herramientas. Exponga 10 herramientas internas: consulta de solo lectura en Postgres, listado de objetos en S3, búsqueda/lectura en Jira, búsqueda/lectura en Linear, consulta de métricas en Datadog, consulta de guardia en PagerDuty, solo lectura en GitHub, búsqueda en Notion, búsqueda en Slack y lectura en Salesforce. Cada herramienta tiene un esquema tipado y una etiqueta de alcance.

2. Servidor FastMCP. Monte las herramientas. Configure el transporte StreamableHTTP. Agregue un middleware para la introspección de tokens OAuth y la aplicación de alcances.

3. Directiva OPA. Directiva Rego por herramienta: qué alcances permiten la invocación, qué redacción de PII se aplica y qué límites de tamaño de payload se imponen. El servicio de decisión se invoca en cada llamada a una herramienta.

4. Servicio de registro. Servicio Go o TS independiente que recopila .well-known/mcp-capabilities de los servidores registrados, los valida con JSON Schema y ofrece una UI de listado / búsqueda / validación / activación y desactivación.

5. Manifiesto de capacidades. Cada servidor expone .well-known/mcp-capabilities con: lista de herramientas, requisitos de autenticación, URL de transporte, equipo propietario y SLO.

6. Separación de herramientas destructivas. Las herramientas que mutan el estado (creación en Jira, creación en Linear, escritura en Postgres) residen en un segundo servidor MCP con un flujo de autenticación más estricto: los tokens deben contar con un alcance approved:by:human elevado mediante tarjeta de Slack dentro de los últimos 15 minutos.

7. Log de auditoría. JSONL de adición (append-only) por tenant: {timestamp, user, tool, args_redacted, response_redacted, outcome}. Redacción de PII mediante Presidio antes de escribir.

8. Prueba de carga. 100 clientes simultáneos sobre StreamableHTTP. Demuestre el escalado horizontal agregando una segunda réplica; muestre cómo el balanceador de carga redistribuye sin persistencia de sesión (sticky sessions).

9. Pruebas de conformidad. Ejecute la suite oficial de conformidad de MCP contra ambos servidores. Supere todas las secciones obligatorias.

Use It

$ curl -H "Authorization: Bearer eyJhbGc..." \
       -X POST https://mcp.internal.example.com/ \
       -d '{"jsonrpc":"2.0","method":"tools/call",
            "params":{"name":"postgres.readonly","arguments":{"sql":"SELECT 1"}}}'
[registry]   capability validated: postgres.readonly v1.2
[policy]    scope postgres:query:readonly present; allowed
[audit]     logged: user=u42 tool=postgres.readonly outcome=ok
response:    { "result": { "rows": [[1]] } }

Ship It

outputs/skill-mcp-server.md describe el entregable. Un servidor MCP de nivel de producción + registro + capa de auditoría para herramientas internas con alcances OAuth 2.1 y control por OPA.

Exercises

1. Agregue una nueva herramienta (búsqueda en Confluence). Despliéguela a través del flujo de validación del registro sin modificar el servidor principal.

2. Escriba una directiva OPA que redacte resultados de consultas de Postgres que contengan columnas llamadas email, ssn o phone. Pruébela con una consulta de prueba.

3. Realice un benchmark entre StreamableHTTP y stdio sobre latencia local. Reporte p50/p95 por llamada.

4. Implemente cuotas por tenant: máximo N llamadas por minuto por herramienta por tenant. Aplique esto mediante una segunda regla de OPA.

5. Ejecute la suite de conformidad de MCP desde mcp-conformance-tests y resuelva cada fallo.

Key Terms

Further Reading

• Model Context Protocol 2026 Roadmap — StreamableHTTP, metadatos de capacidad, registro
• AAIF MCP Registry spec — la especificación del registro de 2026
• AWS ECS reference deployment — despliegue de referencia de producción
• Pinterest internal MCP ecosystem — despliegue interno de referencia
• Block goose MCP usage — patrón de consumo del agente de referencia
• FastMCP — framework de servidor Python
• Open Policy Agent — referencia del motor de directivas
• SPIFFE / SPIRE — referencia de identidad de carga de trabajo