MCP Agent Trace Inspector

MCP Agent Trace Inspector

Pacote npm mcp-agent-trace-inspector

Observabilidade local-first e nativa de MCP para fluxos de trabalho de agentes. Cada chamada de ferramenta, transformação de prompt, latência e contagem de tokens é registrada em um banco de dados SQLite local — sem conta na nuvem, sem chave de API, sem traces saindo da sua máquina. Construído especificamente para MCP, em vez de ser acoplado a um proxy LLM genérico.

Referência de ferramentas | Configuração | Contribuição | Solução de problemas | Princípios de design

Principais recursos

• Rastreamento de chamadas de ferramentas: captura entradas, saídas, latência e uso de tokens para cada etapa de um fluxo de trabalho.
• Armazenamento persistente: os traces sobrevivem a reinicializações de sessão; armazenados localmente em SQLite, sem dependências externas.
• Dashboard HTML: gera um dashboard autossuficiente em arquivo único com uma linha do tempo interativa de etapas.
• Estimativa de custo de tokens: calcula o custo em USD por trace usando uma tabela de preços de modelos configurável — sem chamadas de API.
• Comparação de traces: compare dois traces lado a lado para medir o impacto de alterações em prompts ou ferramentas.
• Baixa sobrecarga: adiciona menos de 5ms por etapa; nunca se torna o gargalo.

Por que usar isto em vez de LangSmith / AgentOps?

	mcp-agent-trace-inspector	LangSmith / AgentOps
Localização dos dados	SQLite local — nunca sai da sua máquina	Hospedado na nuvem; traces enviados para servidores externos
Configuração	npx one-liner, zero configuração	Cadastro de conta, chave de API, instrumentação de SDK
Ciente de MCP	Nativo — registra chamadas de ferramentas como etapas de primeira classe	Proxy LLM genérico; estrutura MCP é opaca
Executar diffs	Diff compare_traces integrado	Recurso pago separado ou exportação manual
Estimativa de custo	tiktoken offline + tabela de preços configurável	Requer tráfego de API ao vivo através do proxy deles
Sobrecarga	<5ms por etapa	Round-trip de rede por evento

Se seus traces contêm saídas sensíveis de ferramentas, prompts proprietários ou dados que devem permanecer no dispositivo, esta é a ferramenta certa. Se você precisa de compartilhamento de traces entre equipes ou de um SaaS gerenciado, use o LangSmith.

Avisos

mcp-agent-trace-inspector armazena entradas e saídas de chamadas de ferramentas localmente em um banco de dados SQLite. Os traces podem conter informações sensíveis passadas ou retornadas pelas suas ferramentas. Revise o conteúdo dos traces antes de compartilhar exportações de dashboard. Os traces não são transmitidos automaticamente; webhooks de alerta opcionais estão disponíveis.

Requisitos

• Node.js v22.5.0 ou mais recente.
• npm.

Primeiros passos

Adicione a seguinte configuração ao seu cliente MCP:

{
  "mcpServers": {
    "trace-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-agent-trace-inspector@latest"]
    }
  }
}

Para definir um caminho de armazenamento personalizado:

{
  "mcpServers": {
    "trace-inspector": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-agent-trace-inspector@latest",
        "--db=~/traces/my-project.db"
      ]
    }
  }
}

Configuração do cliente MCP

Amp · Claude Code · Cline · Cursor · VS Code · Windsurf · Zed

Seu primeiro prompt

Digite o seguinte no seu cliente MCP para verificar se tudo está funcionando:

Start a trace called "test-run", then list the files in the current directory, then end the trace and show me the summary.

Seu cliente deve retornar um resumo mostrando a contagem de etapas, o total de tokens e a latência.

Ferramentas

Ciclo de vida do trace (3 ferramentas)

• trace_start — inicia um novo trace; retorna um trace_id para chamadas subsequentes
• trace_step — registra uma etapa de chamada de ferramenta (entradas, saídas, contagem de tokens e latência opcionais)
• trace_end — marca um trace como concluído

Inspeção (4 ferramentas)

• list_traces — lista traces armazenados com nomes, status e timestamps
• get_trace_summary — totais de tokens, contagem de etapas, latência e estimativa de custo de um trace
• compare_traces — compara dois traces lado a lado (contagens de etapas, tokens, latência)
• extract_reasoning_chain — extrai apenas as etapas de raciocínio/pensamento de um trace

Exportação (3 ferramentas)

• export_dashboard — gera um dashboard HTML autossuficiente em arquivo único com waterfall de latência
• export_otel — exporta um ou todos os traces no formato de spans OpenTelemetry OTLP JSON
• export_compliance_log — exporta o log de auditoria de conformidade como JSON ou CSV, com filtragem opcional por intervalo de datas

Operações (3 ferramentas)

• configure_alerts — configura regras de alerta sobre latência, taxa de erro ou custo; envia para Slack ou webhooks genéricos
• set_retention_policy — define por quantos dias manter os traces (em memória; deve ser chamado antes de apply_retention)
• apply_retention — arquiva traces mais antigos que o limite configurado; exclui traces além de 2x o limite

Configuração

--db / --db-path

Caminho para o arquivo de banco de dados SQLite usado para armazenar traces.

Tipo: string Padrão: ~/.mcp/traces.db

--retention-days

Exclui automaticamente traces mais antigos que N dias. Defina como 0 para desativar.

Tipo: number Padrão: 0

--pricing-table

Caminho para um arquivo JSON contendo preços personalizados de modelos ($/1K tokens). Substitui a tabela integrada.

Tipo: string

--no-token-count

Desativa a contagem de tokens baseada em tiktoken. Os traces omitirão as métricas de uso de tokens.

Tipo: boolean Padrão: false

Passe as flags pela propriedade args na sua configuração JSON:

{
  "mcpServers": {
    "trace-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-agent-trace-inspector@latest", "--retention-days=30"]
    }
  }
}

Princípios de design

• Traces somente anexação: as etapas são imutáveis após o registro. Confiança exige integridade.
• Local-first: toda a funcionalidade principal funciona sem conexão de rede.
• Dashboards portáteis: as exportações HTML são sempre em arquivo único; nenhum servidor é necessário para visualizá-las.

Verificação

Antes de publicar uma nova versão, verifique o servidor com o MCP Inspector para confirmar que todas as ferramentas estão expostas corretamente e que o handshake do protocolo é bem-sucedido.

Interface interativa (abre o navegador):

npm run build && npm run inspect

Modo CLI (scriptado / amigável para CI):

# List all tools
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

# List resources and prompts
npx @modelcontextprotocol/inspector --cli node dist/index.js --method resources/list
npx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list

# Call a tool (example — replace with a relevant read-only tool for this plugin)
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name list_traces

# Call a tool with arguments
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name list_traces --tool-arg key=value

Execute antes de publicar para detectar regressões no registro de ferramentas e na inicialização do runtime.

Contribuição

Consulte CONTRIBUTING.md para as diretrizes completas de contribuição.

npm install && npm test

Registro e Marketplace MCP

Este plugin está disponível em:

• MCP Registry
• MCP Market

Pesquise por mcp-agent-trace-inspector.