POC — MCP server + client + REST API (observabilidade)

Stack completo e executável: uma API REST de observabilidade, um servidor MCP que a expõe como ferramentas, e um cliente MCP sem LLM que roda um roteiro de investigação real.

O dataset é sintético mas tem uma história plantada: checkout-api v2.4.0 subiu há 3 horas e quebrou o serviço. A ferramenta de correlação precisa encontrar isso sozinha — e encontra.

Para o porquê de cada decisão de design, veja docs/ARCHITECTURE.md.

Rodar

Requer uv e Python 3.14+.

git clone https://github.com/JoaoAndrade18/mcp-server-client-poc.git
cd mcp-server-client-poc
uv sync

./run.sh          # sobe tudo, roda o cenário, derruba
uv run pytest -q  # 18 testes

Arquitetura

   cliente MCP  ──MCP/streamable-http──►  servidor MCP  ──HTTP+Bearer──►  API REST
   (sem LLM)         :8765/mcp              (adapter)        :8081        (dados)
                                                 │
                                            /metrics  /healthz

As três camadas são separadas de propósito:

• A API REST (api.py) não sabe o que é MCP. É o "sistema que já existe" na sua empresa. O servidor MCP é um adaptador na frente dela, não uma reescrita.
• O servidor MCP (mcp_server.py) não tem dados. Traduz protocolo e guarda o token da API. Quem fala MCP nunca vê essa credencial.
• O cliente (client.py) não tem modelo. Tudo que um LLM faria dinamicamente, ele faz por script. Se quebrar, o problema é seu servidor — não o raciocínio do modelo. É o jeito de isolar as duas coisas.

O que o POC demonstra

Área	Onde
Tools com output estruturado (Pydantic)	mcp_server.py — 6 tools
Annotations (readOnlyHint, destructiveHint)	idem — só open_incident escreve
Resources (estáticos + template)	obs://services, obs://service/{name}/runbook
Prompts (workflow reutilizável)	investigate_service
Auth por token + escopos	StaticTokenVerifier, _require_scope
Métricas por tool (calls/erros/latência)	GET :8765/metrics
Health check com upstream	GET :8765/healthz
Erros acionáveis	query_logs("does-not-exist")

Tools

Tool	Tipo	O que faz
list_services	read	Catálogo com time, tier e SLOs
query_logs	read	Busca por serviço, nível, substring, janela
get_metrics	read	Resume 1 métrica + veredito de SLO
get_deploys	read	Histórico de deploys
correlate_deploy_with_errors	read	Antes/depois do último deploy + veredito + confiança
open_incident	write	Abre incidente (exige escopo incidents:write)

correlate_deploy_with_errors é o ponto principal do design: as tools são moldadas por tarefa, não por endpoint. Ela responde "por que X quebrou?" numa chamada só, em vez de obrigar o chamador a costurar get_deploys + 2×get_metrics + query_logs e fazer a aritmética sozinho.

Rodar as partes separadas

# API REST isolada (docs em /docs)
uv run uvicorn obs.api:app --port 8081

# Servidor MCP — HTTP (produção)
uv run python -m obs.mcp_server

# Servidor MCP — stdio (Claude Desktop, IDEs)
MCP_TRANSPORT=stdio uv run python -m obs.mcp_server

# Inspector oficial
uv run mcp dev src/obs/mcp_server.py

Modo autenticado

Por padrão a auth vem desligada para o demo rodar sem fricção. Para ligar:

MCP_REQUIRE_AUTH=1 uv run python -m obs.mcp_server
MCP_TOKEN=mcp_oncall_token uv run python -m obs.client

Comportamento verificado:

Token	list_services	open_incident
nenhum	HTTP 401	HTTP 401
inválido	HTTP 401	HTTP 401
mcp_readonly_token (obs:read)	✅	❌ bloqueado no escopo
mcp_oncall_token (+incidents:write)	✅	✅

Os tokens estáticos são só do POC. Em produção, StaticTokenVerifier vira um verificador de JWT contra o JWKS do seu IdP — o formato do retorno (AccessToken com escopos) é o mesmo.

Nota sobre o /metrics

O p95 do servidor foi o que revelou um bug real durante a construção deste POC: correlate_deploy_with_errors reportava p95 abaixo da média, o que é impossível. A causa era int(n * 0.95) - 1, que com n=2 dá índice 0 e retorna o mínimo. Está corrigido em percentile() e travado por teste.

É o argumento para instrumentar o servidor MCP desde o dia 1: sem o /metrics o bug teria passado.

Estrutura

src/obs/
  data.py        dataset determinístico (seed fixa, incidente plantado)
  api.py         API REST — FastAPI, bearer auth, /metrics
  mcp_server.py  servidor MCP — tools, resources, prompts, auth, métricas
  client.py      cliente MCP — sem LLM, roteiro fixo
tests/test_poc.py
run.sh