---
title: "O que registrar em cada chamada de ferramenta MCP"
description: "Um cliente vê um servidor MCP remoto como um único span opaco, e um painel de diretório vê totais. Só o servidor viu a chamada. A linha que os servidores MCP da Tajo gravam para cada uma, campo a campo, o que é removido dela e o que não está construído."
url: https://tajo.io/pt/blog/what-to-log-for-every-mcp-tool-call/
markdown: https://tajo.io/pt/blog/what-to-log-for-every-mcp-tool-call.md
lang: pt-BR
author: "Set Noa"
author_url: https://tajo.io/pt/set-noa/
published: 2026-11-06
updated: 2026-11-06
alternates: {en-US: /blog/what-to-log-for-every-mcp-tool-call.md, bg-BG: /bg/blog/what-to-log-for-every-mcp-tool-call.md, cs-CZ: /cz/blog/what-to-log-for-every-mcp-tool-call.md, de-DE: /de/blog/what-to-log-for-every-mcp-tool-call.md, da-DK: /dk/blog/what-to-log-for-every-mcp-tool-call.md, es-ES: /es/blog/what-to-log-for-every-mcp-tool-call.md, fr-FR: /fr/blog/what-to-log-for-every-mcp-tool-call.md, el-GR: /gr/blog/what-to-log-for-every-mcp-tool-call.md, hi-IN: /hi/blog/what-to-log-for-every-mcp-tool-call.md, id-ID: /in/blog/what-to-log-for-every-mcp-tool-call.md, hr-HR: /hr/blog/what-to-log-for-every-mcp-tool-call.md, hu-HU: /hu/blog/what-to-log-for-every-mcp-tool-call.md, it-IT: /it/blog/what-to-log-for-every-mcp-tool-call.md, ja-JP: /jp/blog/what-to-log-for-every-mcp-tool-call.md, ko-KR: /kr/blog/what-to-log-for-every-mcp-tool-call.md, ar-SA: /ar/blog/what-to-log-for-every-mcp-tool-call.md, nl-NL: /nl/blog/what-to-log-for-every-mcp-tool-call.md, no-NO: /no/blog/what-to-log-for-every-mcp-tool-call.md, pl-PL: /pl/blog/what-to-log-for-every-mcp-tool-call.md, ro-RO: /ro/blog/what-to-log-for-every-mcp-tool-call.md, ru-RU: /ru/blog/what-to-log-for-every-mcp-tool-call.md, sv-SE: /se/blog/what-to-log-for-every-mcp-tool-call.md, zh-CN: /zh-cn/blog/what-to-log-for-every-mcp-tool-call.md, sl-SI: /sl/blog/what-to-log-for-every-mcp-tool-call.md, sr-Latn-RS: /sr/blog/what-to-log-for-every-mcp-tool-call.md, th-TH: /th/blog/what-to-log-for-every-mcp-tool-call.md, tr-TR: /tr/blog/what-to-log-for-every-mcp-tool-call.md, ur-PK: /ur/blog/what-to-log-for-every-mcp-tool-call.md, vi-VN: /vi/blog/what-to-log-for-every-mcp-tool-call.md, sk-SK: /sk/blog/what-to-log-for-every-mcp-tool-call.md}
---

[Agentes de IA](https://tajo.io/pt/blog/?category=ai-agents)

# O que registrar em cada chamada de ferramenta MCP

Um cliente vê um servidor MCP remoto como um único span opaco, e um painel de diretório vê totais. Só o servidor viu a chamada. A linha que os servidores MCP da Tajo gravam para cada uma, campo a campo, o que é removido dela e o que não está construído.

logs de servidor MCP

O que um servidor MCP deve anotar em cada chamada de ferramenta?

Registre uma linha por chamada de ferramenta, no servidor, porque o servidor é o único lugar que a viu. Os servidores MCP da Tajo anotam quem chamou (o ID da chave, nunca o seu segredo), qual servidor e qual conector, a ferramenta se ela existir, sua classe de efeito, ok ou um código de erro curto, duração, tamanho do resultado, ID de trace, os registros que a chamada tocou, e os argumentos e a resposta limpos de segredos e dados pessoais. As linhas são lidas com logs.list e logs.get e excluídas após 30 dias. Elas ficam separadas do log de auditoria encadeado por hash, onde as aprovações e os digests das suas entradas são guardados. Não construído: um score de saúde, um alerta de taxa de erros, a busca por ferramenta ou por ID de trace e a exportação para o seu próprio sistema de tracing.

[Saiba mais](https://tajo.io/pt/blog/what-to-log-for-every-mcp-tool-call/#uma-linha-por-chamada)

Em 8 de junho de 2026, a Anthropic deu aos donos de conectores do diretório do Claude um painel. Ele mostra usuários ativos, o total de chamadas de ferramentas e a posição no diretório. Ele mostra “[score de saúde, taxas de erro e latência num relance, com detalhamento de erros por ferramenta para identificar exatamente o que está falhando](https://claude.com/resources/articles/observability-for-developers-building-connectors)”.

Um ano antes, Alex Volkov, da Weights & Biases, tinha descrito o mesmo problema pelo outro lado. Assim que o agente dele passou a chamar ferramentas via MCP, “[toda aquela observabilidade com que estou acostumado quando o meu próprio código roda de ponta a ponta ficou meio às escuras](https://www.youtube.com/watch?v=Lcqat4iP_lE&t=61s)”. O colega de palestra dele, Benjamin Eckel, da Dylibso, mostrou por quê. Um servidor MCP remoto “[aparece para nós no trace como um único span de serviço](https://www.youtube.com/watch?v=Lcqat4iP_lE&t=447s)”, porque roda fora do controle de quem chama.

As duas visões ficam do lado de fora do servidor. O cliente vê um span opaco. O diretório vê totais. Nenhum dos dois viu o que foi pedido ao servidor, o que ele recusou e o que ele tocou. Só o servidor viu, então só o servidor pode anotar.

É isto que os servidores MCP da Tajo anotam, lido do código que os executa e [descrito na documentação](https://tajo.io/pt/docs/mcp/#mcp-request-log). [O que é um servidor MCP](https://tajo.io/pt/blog/what-is-an-mcp-server/) cobre o protocolo. Aqui o assunto é a linha.

## Uma linha por chamada

Um painel é a visão do capitão do porto: navios que entram, navios que saem, quais se atrasaram. O log de requisições é o diário de bordo do próprio navio, escrito a bordo, na hora.

Cada `tools/call` no servidor do workspace da Tajo e em cada servidor de conector [termina em uma linha](https://tajo.io/pt/docs/mcp/#mcp-request-log). A linha é gravada depois que a resposta é montada, seja qual for a resposta. Uma chamada recusada porque a chave não pode gravar, ou porque o endpoint é somente leitura, ganha uma linha como qualquer outra. O mesmo vale para uma chamada a uma ferramenta que não existe.

Eis o que a linha guarda, e o que ela se recusa a guardar.

| Campo | Guardado | Não guardado |
| --- | --- | --- |
| Quem | O ID da chave de API que chamou. Um token de um login OAuth também é uma chave. | O segredo da chave ou o seu prefixo. |
| Onde | O servidor do workspace ou um servidor de conector, com o seu conector e o seu perfil. |  |
| Ferramenta | O nome, quando o servidor tem uma ferramenta com esse nome. | Qualquer outro nome que o cliente envie: ele é armazenado como `(unknown)`. |
| Efeito | `read`, `write`, `send` ou `destructive`: o efeito mais pesado que a chamada poderia ter. |  |
| Resultado | `ok`, ou um código de erro curto em snake\_case como `unknown_tool`. | Texto de erro: tudo o que não é um código é armazenado como `tool_error`. |
| Duração e tamanho | Os milissegundos da chegada até a resposta, e os bytes que quem chamou recebeu. |  |
| ID de trace | O ID da requisição, de um header `x-request-id`, `x-trace-id` ou W3C `traceparent`, ou então um novo. | Um valor de header que não seja hexadecimal nem um UUID. |
| Registros | Até 20 IDs de registros que a chamada nomeou ou produziu: um contato, uma mensagem, uma aprovação. | Os próprios registros. |
| Corpos | Os argumentos e a resposta, [limpos](https://tajo.io/pt/docs/mcp/#mcp-request-log), no máximo 4 KB cada. | Segredos, texto livre e os dados pessoais listados abaixo. |

Três dessas recusas dizem respeito ao cliente, não aos dados. Um nome de ferramenta, um código de erro e um ID de trace chegam todos de fora. Cada um é guardado só num formato pelo qual o servidor pode responder. Um log que armazena o que quer que quem chamou tenha enviado pode ser preenchido com qualquer coisa, inclusive o endereço de e-mail de um cliente na coluna do nome da ferramenta.

A pergunta em aberto de Benjamin Eckel no fim da palestra era como um coletor sabe “[que é uma chamada de ferramenta MCP que tem um erro](https://www.youtube.com/watch?v=Lcqat4iP_lE&t=906s)”. Em um único servidor, a resposta é uma coluna. `ok` é false, e o código diz qual erro.

## Os argumentos: uma regra que invertemos

A objeção é justa, e é nossa. Registre os argumentos e você terá construído uma segunda cópia dos dados dos seus clientes, fora do alcance de qualquer pedido de exclusão. Até 18 de outubro de 2026, essa era [a nossa própria regra](https://tajo.io/pt/docs/mcp/#mcp-request-log). O log não guardava nem os argumentos nem o corpo do resultado, porque os dois podem conter dados pessoais.

Foi a troca errada. Um log de requisições que não consegue mostrar o que foi enviado e o que voltou não consegue responder à única pergunta para a qual ele existe: por que a chamada do meu agente falhou?

Então os corpos são guardados, e o motivo pelo qual não eram é atendido de outra forma. Cada corpo passa por [uma passagem determinística](https://tajo.io/pt/docs/mcp/#mcp-request-log) antes de entrar na fila.

- **Nenhum segredo sobrevive.** Um campo cujo nome indica token, senha, segredo, assinatura, cookie, sessão ou umas vinte palavras parecidas guarda só `[secret]`. O mesmo vale para um valor com um formato conhecido de credencial, onde quer que apareça. Isso cobre bearer tokens, JWTs, chaves privadas, URLs com senha e qualquer sequência opaca de 40 ou mais caracteres de chave.
- **Prosa não é guardada de jeito nenhum.** Um campo chamado `html`, `text`, `body`, `markdown` ou `content` guarda só `[redacted]`. A prosa contém nomes e endereços postais que nenhum padrão encontra.
- **Dados pessoais são mascarados de vez.** Um campo cujo nome indica dado pessoal, como um e-mail, um telefone, um nome, um endereço ou uma nota, guarda só `[redacted]`. Um endereço de e-mail, um número de telefone, um cartão ou um IBAN dentro de qualquer outra string é mascarado.
- **Os corpos continuam pequenos.** [Strings são cortadas em 512 caracteres](https://tajo.io/pt/docs/mcp/#mcp-request-log), listas em 20 itens, objetos em 50 chaves e o aninhamento em 6 níveis. O corpo inteiro é [cortado em 4 KB](https://tajo.io/pt/docs/mcp/#mcp-request-log) e marcado como truncado.

Dois tipos de chamada guardam menos. Contatos que o chat de uma pessoa trouxe de outro app são registrados como um marcador e uma contagem, nunca como corpo. Uma chamada que lê o log não guarda resposta, já que a resposta seria só outras linhas do log.

Agora, o custo. O mascaramento é permanente, não uma criptografia com uma chave que alguém guarda. O log não consegue mostrar o endereço de e-mail que deu bounce. Ele mostra o ID do contato, e o contato, sob as suas próprias regras, está a uma chamada de distância. O log fica fora da varredura de exclusão do workspace, e é por isso que o mascaramento não pode esperar por uma.

## Por que o log não é a trilha de auditoria

A Tajo já tem [um log de auditoria só de inclusão](https://tajo.io/pt/docs/mcp/#mcp-request-log). Cada linha carrega um hash da linha anterior, então uma edição em qualquer ponto quebra a cadeia. Por que não gravar as chamadas de ferramentas ali?

Porque a cadeia tem um preço. Cada inclusão pega um lock por workspace e lê a linha anterior para estender a cadeia. Gravar cada leitura ali colocaria as chamadas de um workspace em fila atrás de um único lock. Também enterraria, sob milhares de leituras, as mudanças de estado que o log de auditoria existe para mostrar.

Então os dois registros se dividem por pergunta. O log de requisições diz o que um agente pediu e o que aconteceu, [por 30 dias](https://tajo.io/pt/docs/mcp/#mcp-request-log). O log de auditoria diz o que mudou, quem permitiu e se alguém editou o registro desde então.

As aprovações ficam do lado da auditoria. Nos perfis de conector da Tajo, [uma ferramenta propose prepara uma ação declarada e uma ferramenta apply a executa depois de aprovada](https://tajo.io/pt/docs/mcp/). Nada chega ao provedor até que a proposta seja aprovada, por uma pessoa ou por uma regra que o workspace ativou. A linha da chamada propose cita, entre os seus registros, a aprovação que ela criou. A aprovação em si está vinculada a um digest SHA-256 da entrada exata. [Uma aprovação cobre a entrada exata que você viu](https://tajo.io/pt/docs/mcp/agent-specification/): mude um campo e ela deixa de corresponder. Quando a gravação acontece, a linha de auditoria dela guarda o digest da entrada e um digest da resposta do provedor, nunca os valores da resposta.

## Quanto custa a linha

Uma linha é uma gravação no banco de dados, e uma gravação tem um commit. [Até 8 de outubro de 2026](https://tajo.io/pt/docs/mcp/#mcp-request-log), cada chamada esperava o próprio commit antes da resposta, cerca de 2,6 ms no nosso host. Para um cliente, isso era um quarto de uma chamada de ferramenta pequena.

Agora a linha é montada quando a chamada termina e colocada na fila. Um flush grava a fila [no máximo 100 ms depois](https://tajo.io/pt/docs/mcp/#mcp-request-log), uma transação por workspace, então muitas chamadas compartilham um mesmo commit. Nada numa linha muda, nem o seu timestamp. Se [5.000 linhas estiverem esperando](https://tajo.io/pt/docs/mcp/#mcp-request-log), a próxima chamada espera o flush em vez de descartar uma linha.

O registro nunca faz uma chamada falhar. Uma gravação que falha é tentada de novo linha por linha, depois registrada e descartada. O que uma interrupção forçada do processo perde é o que estava na fila: [no máximo os últimos 100 ms de chamadas](https://tajo.io/pt/docs/mcp/#mcp-request-log).

## Lendo de volta

[`logs.list`](https://tajo.io/pt/docs/mcp/#mcp-request-log) retorna as chamadas do workspace, das mais recentes para as mais antigas, sem corpos. Ele filtra por período, por resultado ou status HTTP, por origem (MCP ou a API REST, que compartilha a tabela) e por chave de API. Pagina de 50 em 50 por padrão, até 100. `logs.get` retorna uma chamada com o nome atual da chave, o seu status, a sua duração, a requisição e a resposta limpas, e os registros que ela tocou.

Os dois leem só o workspace de quem chama. O ID de uma linha de outro workspace não é encontrado.

Um erro de ferramenta carrega o ID da requisição. Quando o servidor criou esse ID, ou ele chegou como hexadecimal ou UUID, ele é o ID de trace da linha. Um agente que recebeu um erro pode entregar a uma pessoa o único valor que identifica a chamada.

## O que está construído, e o que não está

Construído, no momento em que escrevemos:

- Uma linha por `tools/call` no servidor do workspace e em cada servidor de conector, chamadas recusadas e desconhecidas incluídas.
- [ID da chave, servidor, conector, perfil, ferramenta, efeito, resultado, duração, tamanho do resultado, ID de trace e até 20 registros tocados](https://tajo.io/pt/docs/mcp/#mcp-request-log).
- [Argumentos e respostas limpos](https://tajo.io/pt/docs/mcp/#mcp-request-log), no máximo 4 KB cada.
- [`logs.list` e `logs.get`](https://tajo.io/pt/docs/mcp/#mcp-request-log), restritos ao workspace, com 30 dias de retenção.
- Aprovações vinculadas a um digest da entrada, e gravações aplicadas registradas com digests de entrada e saída no log de auditoria encadeado por hash.

Não construído, e bom saber antes de depender disso:

- Nenhum score de saúde, nenhum gráfico por ferramenta e nenhum alerta para uma taxa de erros em alta. Um resumo por ferramenta de chamadas, erros e durações mais lentas [existe para os operadores da Tajo](https://tajo.io/pt/docs/mcp/#mcp-request-log), não em alguma tela que você possa abrir.
- `logs.list` não filtra por nome de ferramenta nem por ID de trace. Para achar a linha por trás de um ID de requisição, restrinja por período e por chave.
- As linhas não são exportadas para um sistema de tracing que você opera. O ID de trace é lido só dos headers HTTP, não do campo `_meta` do MCP que a palestra usou para [carregar o contexto de trace](https://www.youtube.com/watch?v=Lcqat4iP_lE&t=535s).
- [Depois de 30 dias, uma linha é excluída](https://tajo.io/pt/docs/mcp/#mcp-request-log). Não há arquivo nem exportação.
- O que foi mascarado não pode ser recuperado a partir do log.
- [Uma interrupção forçada pode perder os últimos 100 ms de linhas](https://tajo.io/pt/docs/mcp/#mcp-request-log).

A palestra terminou dizendo que a observabilidade no MCP “[não está distribuída por igual](https://www.youtube.com/watch?v=Lcqat4iP_lE&t=841s)”. Um painel mais adiante na cadeia não resolve isso, e um trace que para na porta do servidor também não. [Uma sincronização que falha precisa do seu próprio registro](https://tajo.io/pt/blog/worker-died-sync-didnt/); o mesmo vale para cada chamada que pediu uma.

O servidor viu a chamada. Mais ninguém viu. Anote ali.

## Perguntas frequentes

**O que um servidor MCP deve registrar em cada chamada de ferramenta?**

Uma linha por chamada, gravada pelo servidor: qual chave de API chamou, qual servidor e qual conector, o nome da ferramenta se a ferramenta existir, sua classe de efeito, ok ou um código de erro curto, a duração, o tamanho do resultado, o ID de trace da requisição, os IDs dos registros que a chamada nomeou ou produziu, e os argumentos e a resposta limpos de segredos e dados pessoais. Os servidores MCP da Tajo gravam essa linha para cada tools/call, chamadas recusadas incluídas, e a mantêm por 30 dias.

**Um log de requisições MCP deve guardar os argumentos das ferramentas?**

Sim, limpos. Um log sem os argumentos não consegue dizer por que uma chamada falhou. A Tajo não guardava nenhum corpo até 18 de outubro de 2026 e agora guarda os dois, depois de uma passagem determinística: segredos viram \[secret\], texto livre e campos pessoais viram \[redacted\], e-mails, telefones, cartões e IBANs são mascarados, e cada corpo é cortado em 4 KB. O mascaramento é permanente, então o log aponta para o registro pelo ID em vez de copiá-lo.

**Por que manter o log de chamadas de ferramentas MCP separado do log de auditoria?**

Porque eles respondem a perguntas diferentes, com custos diferentes. O log de auditoria da Tajo é uma cadeia de hashes de mudanças de estado, e cada inclusão pega um lock por workspace para estender a cadeia. Gravar cada leitura nele colocaria as chamadas de um workspace na fila atrás desse lock e enterraria as mudanças no meio das leituras. As chamadas de ferramentas vão para uma tabela separada, sem cadeia, mantida por 30 dias; as gravações que uma chamada prepara continuam deixando suas próprias linhas de auditoria.

## Artigos relacionados

### [O que é um servidor MCP? Como funcionam o MCP e o MCP UI em 2026](https://tajo.io/pt/blog/what-is-an-mcp-server/)

3 de out. de 2026 · 16 min de leitura

Passo 1 → Passo 6

### [Grok Bot e Brevo: da solicitação de recurso à resposta ao cliente](https://tajo.io/pt/blog/grok-bot-brevo-product-feedback/)

7 de out. de 2026 · 4 min de leitura

3 seções

### [MCP ou CLI é a pergunta errada. Pergunte onde o estado vive.](https://tajo.io/pt/blog/mcp-or-cli-is-the-wrong-question/)

4 de nov. de 2026 · 8 min de leitura

5 seções