🏗️ Your system’s bridge

In module 2.2, the bridge read runtime/exemplos/agenda.csv e runtime/exemplos/erp-vendas.csv. These files imitate what a system without an API provides: a export.

The first step is to find this file on your system. Look in the menus for “Export,” “Reports,” or “Save as CSV.” In Sônia’s client’s ERP, it’s the monthly sales report, saved in a fixed folder.

How to read the diagram: the blue arrows always go from left to right. The system generates the file, the file lands in a folder, and the bridge (highlighted box) reads that folder. Nothing goes back to the ERP: that’s what keeps the risk low.

The bridge doesn’t have the file paths set in stone. Right at the beginning of the server.mjs it asks: is there PONTE_DADOS? If it exists, read from there. If not, use the folder runtime/exemplos/.

This is the actual line from the kit file:

const pastaExemplos = process.env.PONTE_DADOS || join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'exemplos');

function lerCsv(nome) {
  const [cabecalho, ...linhas] = readFileSync(join(pastaExemplos, nome), 'utf8').trim().split('\n');
  const campos = cabecalho.split(',');
  return linhas.map(l => Object.fromEntries(l.split(',').map((v, i) => [campos[i], v])));
}

Recipe R3 says to put the variable in the .mcp.json, in the field env. This way, every time Claude Code connects the bridge, it starts up already pointed at your folder.

{
  "mcpServers": {
    "ponte-modelo": {
      "command": "node",
      "args": ["runtime/pontes/mcp-modelo/server.mjs"],
      "env": { "PONTE_DADOS": "/caminho/da/exportacao" }
    }
  }
}

claude mcp list

ponte-modelo: node runtime/pontes/mcp-modelo/server.mjs - ✔ Connected

What to look for in the table: the last line avoids confusion. The --selftest continues proving the model with the examples; the bridge connected by the agent is what reads your folder.

Each bridge tool has a purpose run(): that’s where the calculation happens. And that’s where the example CSV column names are. This is the run() actual tool resumo_vendas:

run({ agrupar_por = 'cliente' } = {}) {
  const grupos = {};
  let total = 0;
  for (const r of lerCsv('erp-vendas.csv')) {
    const v = Number(r.quantidade) * Number(r.valor_unitario);
    grupos[r[agrupar_por]] = (grupos[r[agrupar_por]] || 0) + v;
    total += v;
  }
  const linhas = Object.entries(grupos).map(([k, v]) => `${k}: R$ ${v.toFixed(2)}`);
  return [...linhas, `TOTAL: R$ ${total.toFixed(2)}`].join('\n');
},

How to read the diagram: on the left, an invented header from some ERP; on the right, the names the code expects. The two lit arrows are the ones used in the calculation. Changing the name in the code connects the right arrow: the rule (quantity times price) doesn’t change.

You don't need to edit the code by hand. Ask the agent, with a written limit: only replace names inside the run(), without creating a tool that writes.

Leia runtime/pontes/mcp-modelo/server.mjs e a primeira linha do meu arquivo </caminho/da/exportacao/vendas.csv>.
Na ferramenta resumo_vendas, troque só os nomes de colunas usados em run() e o nome do arquivo em lerCsv pelos do meu arquivo.
Se o meu arquivo usar ponto e vírgula, ajuste a separação em lerCsv.
Não crie ferramenta que escreve e não mexa em listar_horarios_livres.
Antes de salvar, me mostre o antes e o depois de cada linha alterada.

The server.mjs brings the rule in a comment: "POLITICA: both tools only READ (N4). A tool that writes needs another level and confirmation."

Reading is N4: the agent does it on its own, without notifying you, because nothing changes in the world. The temptation appears right away. Clara will want the agent to mark consult, not just list the time. That already counts as writing, and recipe R3 is clear: a tool that writes is raised to "modify" in POLITICA.md, N2, asks first.

A new bridge only counts after a calculation you did yourself. Not because the code makes lots of mistakes, but because a misspelled column name doesn't cause an error: it gives you a wrong number that looks right.

Practice with Sônia's data, which you know. Run the selftest and recalculate the total with a calculator.

node runtime/pontes/mcp-modelo/server.mjs --selftest

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

What to look for in the table: by client, the same account shows Mercado Sol 393.00 (185 + 208), Padaria Lua 352.00 (130 + 222), and Empório Mar 111.00. Adding the three gives 856.00 again. When the bridge reads the real data, do the same with three or four rows you can add up.

Use a tool resumo_vendas da ponte-modelo agrupando por cliente. Mostre a resposta da ferramenta sem arredondar e sem comentar.

The rule in runtime/CAPACIDADES.md applies here: a system without a line isn’t used by the agent. The bridge goes on the map only after you have the numbers in hand, along with the test date.

The file already includes an example for Sônia's case, marked as pending:

| ERP sem API                  | Exportação CSV diária   | 6 | ler ~/erp/export/*.csv          | ler (N4)        | pendente |

| ERP da distribuidora | Exportação CSV + ponte MCP | 6 | tool resumo_vendas da ponte-modelo | ler (N4) | <AAAA-MM-DD> ok |

Acrescente uma linha na tabela de runtime/CAPACIDADES.md para a ponte-modelo lendo a minha exportação: via ponte local por MCP, nível 6, política ler (N4), testado em <data de hoje> ok. Não mude as outras linhas. Mostre a linha antes de salvar.

How to read the diagram: the first three steps are technical; the fourth (highlighted) is what enables use. Skipping a line on the map leaves the agent using a system no one has registered.