Entenda o que é MCP
No módulo 2.1 o Claude chamava um script. Funciona, mas o agente precisa saber o nome do arquivo e montar o comando. Com MCP é diferente: o agente recebe uma lista de ferramentas prontas, cada uma com nome, descrição e campos.
A R3 junta dois degraus da escada. A leitura do arquivo é uma ponte local (degrau 6). A forma de entregar ao agente é MCP (degrau 2). O resultado: um sistema sem API passa a parecer, para o agente, um sistema com ferramentas oficiais.
🆕 Novo aqui? Cinco palavras deste módulo
- MCP (Model Context Protocol) — um padrão aberto para ligar ferramentas a agentes de IA. O Claude Code e o Codex falam MCP, então a mesma ponte serve aos dois.
- Servidor MCP — o programa que oferece as ferramentas. Aqui ele roda na sua máquina, aberto pelo próprio agente, sem site nem nuvem.
- Ferramenta (tool) — uma ação com nome que o agente pode chamar, como
listar_horarios_livres. - JSON — texto organizado em pares "nome: valor", entre chaves. É como agente e servidor trocam pedidos e respostas.
- stdio — conversa pelo terminal: o agente escreve na entrada do servidor e lê a saída dele. Nenhuma porta de rede é aberta.
Como ler o desenho: à esquerda, quem pede; no meio, a ponte, que conhece as regras; à direita, os arquivos. As setas tracejadas para os arquivos são só de leitura: a ponte nunca grava neles.
✗ CSV solto na pasta
- ✗ O agente adivinha colunas a cada pedido
- ✗ Cada conversa pode somar de um jeito
- ✗ Nada impede o agente de editar o arquivo
✓ CSV atrás de uma ferramenta
- ✓ Nome e descrição dizem o que ela faz
- ✓ A conta é sempre a mesma, escrita no código
- ✓ Só leitura por construção
padrão aberto de ferramentas
roda na sua máquina
ação com nome
sem porta de rede
Conheça as duas ferramentas da ponte-modelo
O modelo mora em runtime/pontes/mcp-modelo/server.mjs. É um servidor MCP sem dependências: não precisa instalar pacote nenhum, só ter o Node.
Ele traz duas ferramentas de exemplo, uma para cada personagem do curso. A descrição de cada uma é o que o agente lê para decidir quando usá-la.
| Ferramenta | Lê | Campos (opcionais) | Caso |
|---|---|---|---|
listar_horarios_livres | agenda.csv | data (AAAA-MM-DD) e profissional | clínica com agenda em planilha |
resumo_vendas | erp-vendas.csv | agrupar_por: cliente ou produto | contador(a) com exportação do ERP |
O que olhar na tabela: os campos são opcionais. Sem data, a primeira lista todos os horários livres; sem agrupar_por, a segunda agrupa por cliente.
data,hora,profissional,status,paciente 2026-10-06,08:00,Dra. Ana,ocupado,Paciente 01 2026-10-06,09:00,Dra. Ana,livre, 2026-10-06,10:00,Dra. Ana,livre, 2026-10-06,14:00,Dr. Bruno,ocupado,Paciente 02 2026-10-06,15:00,Dr. Bruno,livre, 2026-10-07,08:00,Dra. Ana,livre, 2026-10-07,09:00,Dra. Ana,ocupado,Paciente 03 2026-10-07,16:00,Dr. Bruno,livre,
livre. Três em 06/10 e duas em 07/10. Você vai reencontrar essas linhas nos próximos tópicos.💡 A descrição é metade da ferramenta
O agente não lê o código da ponte; ele lê a descrição. A da primeira diz: "Lista horários livres da agenda da clínica (agenda.csv). Filtros opcionais: data (AAAA-MM-DD) e profissional." Uma descrição clara faz o agente escolher a ferramenta certa sem você mandar.
a agenda da Clara
o ERP da Sônia
o que o agente lê
só o Node
Teste a ponte sozinha
Mesma regra do módulo 2.1: primeiro sem agente. O servidor tem um modo de autoteste, --selftest. Ele lista as ferramentas, chama cada uma com dados de exemplo e imprime o resultado.
Não gasta cota nenhuma: nenhum modelo de IA entra nesse teste. É só o Node lendo os CSVs.
No terminal, dentro da pasta do kit:
node runtime/pontes/mcp-modelo/server.mjs --selftest
Saída real (05/10/2026, Linux):
tools: 2 (listar_horarios_livres, resumo_vendas) 2026-10-06 09:00 · Dra. Ana 2026-10-06 10:00 · Dra. Ana 2026-10-06 15:00 · Dr. Bruno TOTAL: R$ 856.00
tools: 2, os três horários livres de 06/10 e TOTAL: R$ 856.00. É a prova da R3.Os três horários batem com as linhas livre de 06/10 que você viu no tópico anterior. Falta conferir o total da Sônia. O autoteste mostra só a última linha do resumo; a tabela abaixo refaz a conta à mão, linha por linha do erp-vendas.csv.
| Cliente | Linhas do CSV | Total |
|---|---|---|
| Mercado Sol | 10 × 18,50 + 40 × 5,20 = 185 + 208 | R$ 393,00 |
| Padaria Lua | 25 × 5,20 + 12 × 18,50 = 130 + 222 | R$ 352,00 |
| Empório Mar | 6 × 18,50 | R$ 111,00 |
| TOTAL | 393 + 352 + 111 | R$ 856,00 |
O que olhar na tabela: a conta feita à mão chega ao mesmo TOTAL: R$ 856.00 da ponte (o ponto no lugar da vírgula é só o formato do programa).
💡 Confira uma vez na mão
Na primeira vez que uma ponte mexe com dinheiro, refaça a conta numa calculadora. Depois disso, o autoteste vira o seu alarme: se o total mudar sem o CSV mudar, algo quebrou.
a prova da R3
as duas ferramentas
conferido à mão
nenhum modelo no teste
Conecte a ponte ao Claude Code
No kit, essa parte já vem feita. Dois arquivos cuidam dela: o .mcp.json, na raiz, registra a ponte; o .claude/settings.json libera o uso dela.
Quando você abre claude na pasta, ele lê o .mcp.json e liga o servidor sozinho. Você não precisa deixar nada rodando.
📄 .mcp.json (registra)
{
"mcpServers": {
"ponte-modelo": {
"command": "node",
"args": ["runtime/pontes/mcp-modelo/server.mjs"]
}
}
}
📄 .claude/settings.json (libera, trecho)
"enabledMcpjsonServers": [ "ponte-modelo" ]
Sem essa linha, o Claude Code pergunta antes de ligar um servidor que veio no projeto.
No terminal, dentro da pasta do kit:
claude mcp list
Saída real (05/10/2026, Linux), a linha da ponte:
ponte-modelo: node runtime/pontes/mcp-modelo/server.mjs - ✔ Connected
ponte-modelo termina em ✔ Connected. Se aparecer Pending approval, abra claude na pasta uma vez e aprove.Registrar
.mcp.json diz o nome da ponte e o comando que a liga.
Liberar
enabledMcpjsonServers aprova a ponte deste projeto, ou você aprova na primeira abertura.
Conferir
claude mcp list mostra ✔ Connected. Só então peça algo ao agente.
🆕 Novo aqui? Num projeto que não é o kit
Fora da pasta do kit não há .mcp.json pronto. O próprio server.mjs traz, num comentário no topo, o comando que registra a ponte: claude mcp add ponte-modelo -- node runtime/pontes/mcp-modelo/server.mjs. Tudo depois do -- é o comando que liga o servidor.
Use a ferramenta pelo agente
Agora o agente entra. O comando abaixo usa claude -p: manda um pedido único, sem abrir a tela, e imprime a resposta. Ele pede os horários de 07/10, um dia diferente do autoteste.
Trocar o dia é de propósito. Se o agente responder certo um dia que você não testou, é sinal de que ele chamou a ferramenta, e não repetiu algo que já tinha visto.
No terminal, dentro da pasta do kit:
claude -p "Use a tool listar_horarios_livres da ponte-modelo e diga os horários livres de 2026-10-07."
Resultado provado no CHANGELOG 0.2.0:
A resposta traz 08:00 (Dra. Ana) e 16:00 (Dr. Bruno), exatamente as linhas livre de 07/10 no CSV. O texto em volta muda de uma vez para outra; os dois horários, não.
agenda.csv do tópico 2 e confira as duas linhas de 2026-10-07 com livre.Como ler o desenho: a caixa com brilho é o único ponto em que a IA decide algo: qual ferramenta chamar e com qual data. O filtro do passo 3 é código, não palpite.
A Sônia faz o mesmo com a outra ferramenta. Com claude aberto na pasta do kit, ela pede: "Use a tool resumo_vendas da ponte-modelo agrupando por cliente e me diga quem comprou mais." A resposta tem de bater com a tabela do tópico 3: Mercado Sol na frente, com R$ 393,00.
⚠️ A ponte só lê, e deve continuar assim
As duas ferramentas só leem (N4). Se um dia você criar uma que marca consulta ou grava no ERP, ela sobe para "alterar" na POLITICA.md: N2, pede antes a cada vez. Ferramenta que escreve nunca entra como "sempre permitir".
pedido sem tela
dia fora do autoteste
N4
sobe para N2
Conecte a mesma ponte ao Codex
O Codex não lê o .mcp.json. Ele tem o próprio registro, feito por um comando. A ponte é a mesma: nenhuma linha do server.mjs muda.
Repare no "$PWD/…": a receita registra no Codex o caminho completo do servidor, começando da raiz do disco, e não o caminho curto que o .mcp.json usa. Assim o registro não depende de onde o Codex foi aberto.
No terminal, dentro da pasta do kit:
codex mcp add ponte-modelo -- node "$PWD/runtime/pontes/mcp-modelo/server.mjs"
Resultado esperado (pela receita):
A R3 não traz prova própria para este passo. O teste é pedir ao Codex o mesmo que você pediu ao Claude.
codex na pasta do kit e peça: "Use a tool listar_horarios_livres da ponte-modelo e diga os horários livres de 2026-10-07." Tem de voltar 08:00 (Dra. Ana) e 16:00 (Dr. Bruno).| Claude Code | Codex | |
|---|---|---|
| Onde registra | .mcp.json do projeto (já vem no kit) | comando codex mcp add |
| Caminho do servidor | relativo à pasta do kit | completo, com "$PWD/…" |
| Como conferir | claude mcp list → ✔ Connected | pedir os horários de 07/10 |
| Ponte usada | a mesma: runtime/pontes/mcp-modelo/server.mjs | |
O que olhar na tabela: só a forma de registrar muda. É por isso que MCP compensa: você escreve a ponte uma vez e qualquer agente que fala MCP a usa.
💡 E o seu próprio sistema?
A ponte-modelo lê os CSVs de exemplo. Para ler a exportação do seu sistema, o kit prevê a variável PONTE_DADOS=/caminho/da/exportacao, no campo env do .mcp.json. É o assunto do módulo 2.3, com as colunas trocadas e o registro no CAPACIDADES.md.
Teste rápido (opcional): o claude mcp list mostra ponte-modelo … ✔ Connected. O que isso prova?
dois agentes
registro do Codex
caminho completo
seu sistema, no 2.3
🎓 Resumo do módulo
Próximo módulo:
2.3 — A ponte do seu sistema