Phase 19 - Lesson 13

Capstone 13 — Servidor MCP com Registro e Governança

O Model Context Protocol deixou de ser o futuro e tornou-se a especificação padrão de uso de ferramentas em 2026. Anthropic, OpenAI, Google e todas as principais IDEs contam com clientes MCP nativos. O Pinterest publicou seu ecossistema interno de servidores MCP. O AAIF Registry formalizou os metadados de capacidades no caminho .well-known. O AWS ECS publicou a implantação stateless de referência. O goose-agent do Block embutiu o mesmo protocolo dentro de um assistente hospedado. O formato de produção de 2026 consiste em: transporte StreamableHTTP, escopos OAuth 2.1, controle de políticas por OPA e um registro que permite às equipes de plataforma descobrir, validar e ativar servidores. Construa isso de ponta a ponta.

Type: Capstone Languages: Python (servidor, via FastMCP) ou TypeScript (@modelcontextprotocol/sdk), Go (serviço 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

O MCP tornou-se a língua franca para o uso de ferramentas. Claude Code, Cursor 3, Amp, OpenCode, Gemini CLI e todos os agentes gerenciados agora consomem servidores MCP. Os desafios em produção não estão no desenvolvimento de servidores (o FastMCP facilita bastante), mas sim em sua implantação em escala atendendo requisitos corporativos: escopos OAuth por cliente (tenant), política OPA para ferramentas destrutivas, escalabilidade horizontal stateless via StreamableHTTP, um registro para descoberta e logs de auditoria por chamada de ferramenta. O ecossistema interno de MCP do Pinterest e a especificação do AAIF Registry estabelecem o padrão para 2026.

Você construirá um servidor MCP que expõe 10 ferramentas internas (Postgres somente leitura, listagem de S3, Jira, Linear, Datadog, etc.), uma interface de registro para descoberta na plataforma e uma etapa de aprovação humana para ferramentas destrutivas. O teste de carga demonstrará o escalonamento horizontal com StreamableHTTP. O rastreamento de auditoria atende aos requisitos de uma revisão de segurança corporativa.

Concept

A revisão do MCP de 2026 exige o uso do StreamableHTTP como transporte padrão. Diferente do formato anterior baseado em stdio e SSE, o StreamableHTTP é stateless por padrão: um único endpoint HTTP aceita requisições JSON-RPC, transmite respostas (streams) e suporta conexões de longa duração para notificações. Ser stateless permite o escalonamento horizontal atrás de um balanceador de carga.

A autorização é feita via OAuth 2.1 com escopos por ferramenta. Um token carrega escopos como jira:read, s3:list, postgres:query:readonly. O servidor MCP verifica os escopos no momento em que a ferramenta é chamada, e não apenas no início da sessão. Para ferramentas de alto risco, o servidor rejeita qualquer chamada cujo escopo não tenha sido elevado para approved:by:human nos últimos N minutos — elevação que provém de um card de revisão no Slack.

O registro é um serviço independente. Cada servidor MCP expõe um documento .well-known/mcp-capabilities contendo o manifesto de suas ferramentas, a URL de transporte e os requisitos de autenticação. O registro faz varreduras periódicas (polling), valida e indexa esses dados. As equipes de plataforma utilizam a interface do registro para identificar quais ferramentas estão disponíveis, quais escopos necessitam e quais equipes são proprietárias delas.

Architecture

cliente MCP (Claude Code, Cursor 3, ...)
          |
          v
StreamableHTTP sobre HTTPS (JSON-RPC + streaming)
          |
          v
servidor MCP (FastMCP) atrás de balanceador de carga
          |
   +------+------+---------+----------+------------+
   v             v         v          v            v
Postgres    listagem S3  Jira       Linear     Datadog
(somente    (paginado)  (leitura)  (leitura)  (consulta)
leitura)
          |
   +------+-------------+
   v                    v
 barreira política OPA  ferramenta destrutiva MCP (servidor separado)
                        |
                        v
                   aprovação humana via Slack
                        |
                        v
                   log de auditoria (append-only, por tenant)

  serviço de registro
     |
     v  GET /.well-known/mcp-capabilities de cada servidor
     v
     UI: buscar / validar / ativar-desativar / propriedade (ownership)

Stack

• Framework do Servidor: FastMCP (Python) ou @modelcontextprotocol/sdk (TypeScript)
• Transporte: StreamableHTTP sobre HTTPS (stateless)
• Autenticação: OAuth 2.1 com identidade de carga de trabalho (workload identity) via SPIFFE / SPIRE
• Política: Regras OPA / Rego por ferramenta; serviço de decisão de política por requisição
• Registro: auto-hospedado, consome manifestos .well-known/mcp-capabilities
• Aprovação humana: Mensagem interativa do Slack para ferramentas destrutivas
• Implantação: AWS ECS Fargate ou Fly.io, um servidor por tenant ou compartilhado com delimitação de escopo de tenant
• Auditoria: bucket estruturado em formato JSONL por tenant com linhagem de chamadas

Build It

1. Superfície de ferramentas. Exponha 10 ferramentas internas: consulta somente leitura no Postgres, listagem de objetos no S3, busca/leitura no Jira, busca/leitura no Linear, consulta de métricas no Datadog, consulta de plantão no PagerDuty, leitura no GitHub, busca no Notion, busca no Slack e leitura no Salesforce. Cada ferramenta possui um esquema tipado e um rótulo de escopo.

2. Servidor FastMCP. Monte as ferramentas. Configure o transporte StreamableHTTP. Adicione um middleware para introspecção do token OAuth e imposição de escopo.

3. Política OPA. Política Rego por ferramenta: quais escopos permitem a invocação, quais filtros de PII se aplicam e quais são os limites de tamanho do payload. O serviço de decisão é acionado a cada chamada de ferramenta.

4. Serviço de registro. Serviço separado em Go ou TS que consome .well-known/mcp-capabilities dos servidores registrados, valida usando JSON Schema e expõe uma interface de listagem / busca / validação / ativação e desativação.

5. Manifesto de capacidades. Cada servidor expõe .well-known/mcp-capabilities com: lista de ferramentas, requisitos de autenticação, URL de transporte, equipe proprietária e SLO.

6. Separação de ferramentas destrutivas. Ferramentas que alteram estado (criar no Jira, criar no Linear, gravar no Postgres) residem em um segundo servidor MCP com um fluxo de autenticação mais rígido: os tokens devem possuir o escopo approved:by:human elevado via card do Slack nos últimos 15 minutos.

7. Log de auditoria. Arquivo JSONL append-only por tenant: {timestamp, user, tool, args_redacted, response_redacted, outcome}. A remoção de PII é feita via Presidio antes da gravação.

8. Teste de carga. 100 clientes simultâneos em StreamableHTTP. Demonstre o escalonamento horizontal adicionando uma segunda réplica; mostre o balanceador de carga redistribuindo sem a necessidade de afinidade de sessão (sticky sessions).

9. Testes de conformidade. Execute a suíte oficial de testes de conformidade do MCP em ambos os servidores. Passe em todas as seções obrigatórias.

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 descreve o entregável. Um servidor MCP de nível de produção + registro + camada de auditoria para ferramentas internas com escopos OAuth 2.1 e validação por OPA.

Exercises

1. Adicione uma nova ferramenta (busca no Confluence). Implante-a através do fluxo de validação do registro sem alterar o servidor principal.

2. Escreva uma política OPA que remova resultados de consultas do Postgres que contenham colunas chamadas email, ssn ou phone. Realize um teste com uma consulta de teste.

3. Faça um benchmark entre StreamableHTTP e stdio em latência local. Relate o p50/p95 de cada chamada.

4. Implemente cotas por tenant: máximo de N chamadas por minuto, por ferramenta, por tenant. Aplique isso através de uma segunda regra OPA.

5. Execute a suíte de conformidade de MCP a partir de mcp-conformance-tests e corrija todas as falhas.

Key Terms

Further Reading

• Model Context Protocol 2026 Roadmap — StreamableHTTP, metadados de capacidade, registro
• AAIF MCP Registry spec — a especificação de registro de 2026
• AWS ECS reference deployment — implantação de produção de referência
• Pinterest internal MCP ecosystem — a implantação interna de referência
• Block goose MCP usage — padrão de consumo do agente de referência
• FastMCP — framework de servidor em Python
• Open Policy Agent — referência do motor de políticas
• SPIFFE / SPIRE — referência de identidade de carga de trabalho