mcpwatch

---

Aqui está o que ninguém te conta quando você instala um servidor MCP: as definições de ferramentas dele são injetadas no contexto do seu agente no início de cada sessão, quer você use ou não esse servidor. Uma integração grande de fornecedor com 50 ferramentas pode custar mais de 15.000 tokens antes de você digitar uma palavra. Você paga isso de novo na próxima sessão, e na seguinte.

Além disso, você paga por respostas de ferramentas que retornam 200 kB quando você precisava de uma linha, chamadas que falham e são repetidas, e agentes que buscam novamente coisas que já tinham.

Nada disso aparece em lugar nenhum. O mcpwatch registra os bytes reais no fio e os transforma em uma conta detalhada.

Veja seu número em dez segundos

Sem configuração, sem reiniciar, sem esperar. Isso inicia cada servidor MCP que você já tem configurado, pede a lista de ferramentas da mesma forma que seu cliente faz, mede e o encerra:

npx @sreelal727/mcpwatch audit

Every new session pays ~9,262 tokens ($0.05) to load these tool definitions,
before you type a word:

  github         8,825 tokens   52 tools   95%   Cursor
  filesystem       437 tokens    6 tools    5%   Cursor
                 9,262 tokens  every session

At 10 sessions a day that is ~2,778,600 tokens a month ($13.89 at $5/M) spent
before any work happens.

"github" alone is 95% of that. If you do not use it in every project, moving it to
the projects that need it is the single biggest win available to you.

Esse é o custo fixo, e é possível saber sem registrar nada.

Depois descubra o que você realmente usa

Quais dessas ferramentas você chama exige tráfego real. Instrumente uma vez, trabalhe normalmente por um dia e pergunte:

npx @sreelal727/mcpwatch init     # then restart your client
npx @sreelal727/mcpwatch cost     # a day later

Your MCP setup costs ~12,486 tokens per session before you type a word ($0.06 at $5/M tokens).

PER-SESSION TAX — tool definitions loaded into every new session:
  github        10,762 tokens   46 tools, none used  ← never called
  filesystem       780 tokens    8 tools, 2 used
  postgres         944 tokens    9 tools, 1 used
                12,486 tokens, every session

AT YOUR ACTUAL PACE — 34.9 server startups/day over 11.3 days:
  ~4,362,755 tokens/month ($21.81) on tool definitions alone, before any work happens
  ~4,939,089 tokens/month ($24.70) all in

BIGGEST SAVINGS — ~1,510,287 tokens ($7.55) of the above bought you nothing:
  1. 1,420,584 tokens (10,762 of them every session) — github: 46 tools loaded into
     every session, never called
     → Remove "github" from your MCP config (or load it only in projects that need it).
  2. 85,523 tokens — filesystem: 132 repeat calls with identical arguments in the same session
     → The agent re-fetched the same thing — usually a sign it lost the earlier result.
  3. 4,180 tokens — postgres: 33 failed calls
     → Fix or remove postgres's failing calls — each one costs context and a retry too.

Olhe para esses dois primeiros números juntos: US$ 21,81 dos US$ 24,70 da conta mensal são definições de ferramentas — o custo de apenas ter servidores configurados, antes de seu agente fazer uma única coisa útil. E o maior deles nunca foi chamado.

Esse é o objetivo de toda a ferramenta. Não é "aqui está um painel, vá encontrar algo", mas exclua esta linha do seu config e pare de pagar 10.762 tokens a cada sessão por um servidor que você nunca usou.

A projeção usa a taxa de inicialização sua observada a partir da sua gravação — não é um palpite, e não aparece até que haja histórico suficiente para ser honesto.

(Instale uma vez com npm i -g @sreelal727/mcpwatch e todo comando é apenas mcpwatch ….)

Seu agente também pode ler a conta

init também registra o mcpwatch como um servidor MCP, então seu agente recebe essas ferramentas sem configuração extra:

Ferramenta	A pergunta que ela responde
token_costs	"Quanto minha configuração MCP está me custando e o que devo remover?"
recent_failures	"O que acabou de quebrar, com quais argumentos, e o que o servidor disse?"
server_health	"Esse servidor está travando, lento, pendurado ou corrompendo o protocolo?"
find_calls	"Essa ferramenta já funcionou? Quais argumentos usei da última vez?"
get_call	"Mostre o JSON exato de requisição e resposta da chamada #412."

Então você pode simplesmente perguntar, no cliente que já usa:

Você: meu contexto continua enchendo, o que está consumindo?

Agente: (chama token_costs) Seu servidor github carrega 46 definições de ferramentas — 10.762 tokens — em cada sessão, e você não o chamou uma vez nos últimos 30 dias. Isso é cerca de 1,4M de tokens no período. Seu servidor de filesystem também releu arquivos idênticos 132 vezes. Quer que eu remova o github do seu config?

As descrições são escritas como condições de gatilho, então o agente as alcança por conta própria — recent_failures após uma chamada de ferramenta falha, token_costs quando você menciona contexto ou custo — em vez de esperar que lhe digam que elas existem.

Também mostra o que está quebrado

A mesma gravação responde às perguntas de confiabilidade, em um comando:

$ mcpwatch doctor
2 error(s) in 19 MCP calls across 3 server(s) in the last 24h.

! web-fetch        5 calls, no errors, avg 152ms   last seen 32s ago
    1 non-protocol stdout line (this server logs to stdout, which corrupts MCP)
✗ database         7 calls, 2 errors (29%), avg 227ms   last seen 34s ago
    high error rate
    slowest: run_query at 1.3s
✓ filesystem       7 calls, no errors, avg 54ms   last seen 36s ago

[#14] 2s ago  database/does_not_exist  tool_error  (2ms)
    error: MCP error -32602: Tool does_not_exist not found
    session fd14d19f · full payloads: get_call(14)

mcpwatch tail transmite chamadas ao vivo, uma linha cada. Tudo usa --json, então agentes com apenas acesso a shell (Codex em um terminal VS Code, hooks, CI) também podem ler. E mcpwatch ui abre um painel local em 127.0.0.1 quando você prefere olhar você mesmo.

O que você recebe

• Um número em dez segundos — mcpwatch audit precifica seus servidores configurados sem instrumentação, sem reiniciar o cliente e sem esperar por tráfego.
• Uma conta de tokens detalhada — mcpwatch cost precifica o imposto por sessão de cada servidor, projeta para frente a partir do seu próprio uso e classifica o que remover: servidores não usados, listas de ferramentas inchadas, respostas grandes demais, chamadas repetidas, chamadas falhas.
• Gravação legível por agente — token_costs, recent_failures, server_health, find_calls, get_call como ferramentas MCP, além de --json em tudo para agentes que só têm shell. Seu agente para de adivinhar sobre as próprias chamadas de ferramentas.
• Painel ao vivo — sessões chegam em fluxo enquanto seu agente trabalha: linha do tempo de chamadas, pontos de status, barras de latência, inspeção completa de JSON de requisição/resposta, filtragem, claro/escuro.
• Toda chamada registrada — requisição/resposta pareada com duração e status (ok / rpc_error / tool_error), incluindo falhas de ferramentas em banda que clientes muitas vezes engolem silenciosamente.
• Detecção de servidor malcomportado — servidores que escrevem logs no stdout corrompem o protocolo MCP; o mcpwatch registra essas linhas e as sinaliza em vez de quebrar.
• Redação de segredos, ativada por padrão — chaves de API, bearer tokens, JWTs e campos JSON com formato de senha são removidos da cópia armazenada (nunca do fluxo ao vivo). --no-redact para desativar, MCPWATCH_REDACT_EXTRA para adicionar padrões.
• Exportação de sessão — mcpwatch export <id> produz um arquivo HTML autônomo: um relatório de bug compartilhável, sem scripts, do que exatamente aconteceu.
• Servidores HTTP também — mcpwatch http <url> é um proxy reverso de gravação para servidores HTTP Streamable (respostas SSE incluídas).
• Seus dados, seu disco — mcpwatch gc para retenção; exclua ~/.mcpwatch e pronto. Sem SaaS, sem contas, sem telemetria, nunca.

Como funciona

your agent ──stdio──▶ mcpwatch run ──stdio──▶ your MCP server
    ▲                      │
    │                      └── tee ──▶  SQLite (~/.mcpwatch)
    │                                        │
    └──── mcpwatch mcp ◀─────────────────────┤   the agent reads its own history
                                             │
          mcpwatch ui / doctor / tail ◀──────┘   you read it, when you want to

mcpwatch init reescreve cada entrada de servidor stdio no config do seu cliente para rotear através de mcpwatch run. O proxy canaliza bytes intactos e analisa uma cópia do fluxo — a captura é conectada independentemente do repasse, então mesmo se a gravação falhar, seu agente continua funcionando. Repasse é sagrado é o princípio de design nº 1, aplicado em código e coberto por testes de ponta a ponta que dirigem um cliente MCP real através do proxy.

init também adiciona o próprio mcpwatch ao seu cliente como um servidor MCP, o que fecha o ciclo: o gravador se torna uma ferramenta que o agente pode chamar. Ele nunca é envolvido pelo próprio proxy — caso contrário, cada pergunta que o agente fizesse sobre o tráfego se tornaria mais tráfego.

Como se compara

	mcpwatch	MCP Inspector	mcpsnoop	Observabilidade SaaS de agente
Diz quanto sua configuração custa em tokens	✅ cost	❌	❌	parcial (gasto, não imposto por servidor)
Seu agente pode consultar a gravação	✅ Ferramentas MCP	❌	❌	❌
Sessões reais do seu cliente real	✅	❌ ferramenta manual de dev	✅	✅
Fluxo de trabalho headless / só terminal	✅ doctor, tail	❌	✅	❌
Painel web	✅	✅	❌ TUI de terminal	✅
Configuração de cliente inteiro em um comando	✅ init	❌	❌ por servidor	❌ mudanças de SDK/agente
Acompanhamento ao vivo	✅	❌	✅	✅
Exportação de sessão HTML autônoma	✅	❌	❌	❌
100% local, sem conta	✅	✅	✅	❌
Salvaguardas de política	🔜 v1.0	❌	❌	varia

(Todas são boas ferramentas — isso é sobre para qual trabalho cada uma serve. O Inspector é ótimo para cutucar um servidor que você está desenvolvendo; o mcpsnoop é um visualizador de terminal sólido; plataformas SaaS adicionam recursos de frota na infraestrutura delas.)

Comandos

Comando	O que faz
mcpwatch audit [--json]	Mede o custo por sessão dos seus servidores configurados agora — sem configuração
mcpwatch init [--dry-run]	Instrumenta seus clientes e dá ao seu agente as ferramentas do mcpwatch (backups + reversível)
mcpwatch cost [--since 30d] [--rate N] [--json]	Conta de tokens detalhada: imposto por sessão, projeção mensal, economia classificada
mcpwatch doctor [--json]	Relatório de saúde em uma execução: servidores com erro, travando, pendurados, lentos ou corrompendo protocolo
mcpwatch tail [--json]	Acompanhe chamadas ao vivo no terminal, uma linha cada
mcpwatch mcp	Executa o mcpwatch como um servidor MCP (seu cliente inicia isso; você normalmente não vai)
mcpwatch connect	Imprime configuração copiável para Claude Code / Codex / Cursor
mcpwatch unwrap	Restaura configs originais
mcpwatch status	Mostra o que está instrumentado
mcpwatch ui [--port 4680]	Painel local
mcpwatch run --name X -- <cmd>	Envolve um servidor stdio manualmente
mcpwatch http <url> [--port 4681]	Proxy reverso de gravação para um servidor HTTP Streamable
mcpwatch sessions / calls <id>	Visualizações CLI dos dados gravados
mcpwatch export <id> [--out f.html]	Exportação de sessão HTML autônoma
mcpwatch gc [--keep-days 30]	Remove sessões antigas, compacta o banco de dados

FAQ

Quão precisos são os números de tokens? Eles são estimados a partir das contagens de bytes gravados a aproximadamente 4 caracteres por token, não passados por um tokenizador real — enviar um significaria uma dependência nativa em um CLI que as pessoas instalam globalmente. Eles são precisos o suficiente para classificar o que é caro e comparar servidores entre si, que é no que você age. Não reconcilie uma fatura com eles. Os valores em dólares aplicam uma taxa que você pode definir com --rate (padrão US$ 5 por milhão de tokens), e a taxa assumida é sempre impressa.

Isso vai reduzir minha conta de hospedagem ou banco de dados? Não diretamente — o mcpwatch é um gravador local, não infraestrutura. O que ele mostra é trabalho redundante atingindo seus backends: chamadas idênticas repetidas, consultas grandes demais, loops de repetição. Corrigir isso corta cota de API e carga de banco de dados. Mas o título honesto são tokens de contexto, e é aí que a economia realmente está.

A gravação em si custa tokens? Não. A captura é um tee em nível de byte na sua máquina; nada é adicionado a nenhum prompt. As ferramentas do agente só entram no contexto quando o agente realmente chama uma, e as respostas delas são limitadas e resumidas em vez de despejadas.

Sobrecarga? O proxy é um tee em nível de byte; análise e armazenamento acontecem em cópias, fora do caminho crítico do protocolo. Se a captura falhar (disco cheio, o que for), ela se desativa e o tráfego continua fluindo.

Meus dados estão seguros? Eles nunca saem da sua máquina: SQLite em ~/.mcpwatch, painel vinculado a 127.0.0.1, segredos redigidos no momento da gravação por padrão. As ferramentas do agente leem esse mesmo banco de dados local redigido — dar a gravação ao seu agente não a envia para nenhum lugar onde ela já não estava indo.

Meu cliente não foi detectado automaticamente. Execute mcpwatch connect para um trecho copiável para Claude Code (claude mcp add), Codex (~/.codex/config.toml), Cursor ou qualquer outro cliente MCP. Nada nas ferramentas do agente é específico do Claude — é um servidor MCP simples.

O agente lê todo o meu histórico toda vez? Não. As ferramentas retornam respostas limitadas e resumidas (uma dúzia de linhas, argumentos pré-visualizados) e usam por padrão uma janela de tempo recente. Payloads completos só voltam quando o agente pede uma chamada específica.

E as salvaguardas? Isso é v1.0: regras de permitir/negar por servidor/ferramenta, prompts de confirmação para chamadas perigosas e alertas de desvio de descrição de ferramenta (o ataque "puxar o tapete"). O gravador que você usa hoje é a base para isso. Veja ROADMAP.md.

Desenvolvimento

npm install && npm run build && npm test

Monorepo: packages/cli (proxy + CLI + servidor de painel), packages/ui (painel React, compila dentro do pacote CLI). Dados de demonstração para mexer na UI:

cd packages/cli
npx tsx scripts/seed-demo.ts /tmp/mcpwatch-demo.db --keep-running &
node dist/index.js ui --db /tmp/mcpwatch-demo.db

Contribuições são bem-vindas — veja o roadmap para onde as coisas estão indo.

Licença

MIT