MCP Agent Trace Inspector

Observabilidad paso a paso para flujos de trabajo de agentes MCP: rastrea, inspecciona y depura ejecuciones de agentes de múltiples pasos.

GitHubPrueba este MCPPatrocinado

Documentación

MCP Agent Trace Inspector

paquete npm mcp-agent-trace-inspector

Observabilidad local-first y nativa de MCP para flujos de trabajo de agentes. Cada llamada a herramienta, transformación de prompt, latencia y recuento de tokens se registra en una base de datos SQLite local: sin cuenta en la nube, sin clave de API y sin que los traces salgan de tu máquina. Diseñado específicamente para MCP en lugar de acoplado a un proxy LLM genérico.

Referencia de herramientas | Configuración | Contribuciones | Solución de problemas | Principios de diseño

Características principales

Seguimiento de llamadas a herramientas: Captura entradas, salidas, latencia y uso de tokens para cada paso de un flujo de trabajo.
Almacenamiento persistente: Los traces sobreviven a los reinicios de sesión; se almacenan localmente en SQLite sin dependencias externas.
Panel HTML: Genera un panel autónomo de un solo archivo con una línea de tiempo interactiva de pasos.
Estimación de costos de tokens: Calcula el costo en USD por trace mediante una tabla de precios de modelos configurable, sin necesidad de llamadas a API.
Comparación de traces: Compara dos traces en paralelo para medir el impacto de los cambios en prompts o herramientas.
Baja sobrecarga: Añade menos de 5 ms por paso; nunca se convierte en un cuello de botella.

¿Por qué esto en lugar de LangSmith / AgentOps?

	mcp-agent-trace-inspector	LangSmith / AgentOps
Ubicación de datos	SQLite local: nunca sale de tu máquina	Alojado en la nube; los traces se envían a servidores externos
Configuración	`npx` de una línea, cero configuración	Registro de cuenta, clave de API, instrumentación del SDK
Compatible con MCP	Nativo: registra las llamadas a herramientas como pasos de primera clase	Proxy LLM genérico; la estructura de MCP es opaca
Diferencias de ejecuciones	Diff integrado con `compare_traces`	Función paga separada o exportación manual
Estimación de costos	tiktoken sin conexión + tabla de precios configurable	Requiere tráfico de API en vivo a través de su proxy
Sobrecarga	<5 ms por paso	Ida y vuelta de red por evento

Si tus traces contienen salidas sensibles de herramientas, prompts propietarios o datos que deben permanecer en el dispositivo, esta es la herramienta adecuada. Si necesitas compartir traces entre equipos o un SaaS administrado, usa LangSmith.

Avisos

mcp-agent-trace-inspector almacena localmente las entradas y salidas de las llamadas a herramientas en una base de datos SQLite. Los traces pueden contener información sensible pasada o devuelta por tus herramientas. Revisa el contenido de los traces antes de compartir exportaciones del panel. Los traces no se transmiten automáticamente; hay webhooks de alerta opcionales disponibles.

Requisitos

Node.js v22.5.0 o superior.
npm.

Primeros pasos

Añade la siguiente configuración a tu cliente MCP:

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

Para establecer una ruta de almacenamiento personalizada:

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

Configuración del cliente MCP

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

Tu primer prompt

Escribe lo siguiente en tu cliente MCP para verificar que todo funciona:

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

Tu cliente debería devolver un resumen que muestre el número de pasos, el total de tokens y la latencia.

Herramientas

Ciclo de vida de traces (3 herramientas)

trace_start — inicia un nuevo trace; devuelve un trace_id para llamadas posteriores
trace_step — registra un paso de llamada a herramienta (entradas, salidas, recuento de tokens y latencia opcionales)
trace_end — marca un trace como completado

Inspección (4 herramientas)

list_traces — lista los traces almacenados con nombres, estados y marcas de tiempo
get_trace_summary — totales de tokens, número de pasos, latencia y estimación de costo de un trace
compare_traces — compara dos traces en paralelo (número de pasos, tokens, latencia)
extract_reasoning_chain — extrae solo los pasos de razonamiento/pensamiento de un trace

Exportación (3 herramientas)

export_dashboard — genera un panel HTML autónomo de un solo archivo con diagrama de cascada de latencia
export_otel — exporta uno o todos los traces en formato de span JSON OTLP de OpenTelemetry
export_compliance_log — exporta el registro de auditoría de cumplimiento como JSON o CSV, con filtrado opcional por rango de fechas

Operaciones (3 herramientas)

configure_alerts — configura reglas de alerta sobre latencia, tasa de error o costo; envía a Slack o webhooks genéricos
set_retention_policy — establece cuántos días conservar los traces (en memoria; debe llamarse antes de apply_retention)
apply_retention — archiva los traces más antiguos que el umbral configurado; elimina los traces que superen 2 veces el umbral

Configuración

`--db` / `--db-path`

Ruta al archivo de base de datos SQLite utilizado para almacenar traces.

Tipo: string Valor predeterminado: ~/.mcp/traces.db

`--retention-days`

Elimina automáticamente los traces más antiguos de N días. Establece en 0 para desactivar.

Tipo: number Valor predeterminado: 0

`--pricing-table`

Ruta a un archivo JSON que contiene precios personalizados de modelos ($/1K tokens). Reemplaza la tabla integrada.

Tipo: string

`--no-token-count`

Desactiva el recuento de tokens basado en tiktoken. Los traces omitirán las métricas de uso de tokens.

Tipo: boolean Valor predeterminado: false

Pasa las banderas mediante la propiedad args en tu configuración JSON:

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

Principios de diseño

Traces de solo añadidura: Los pasos son inmutables una vez registrados. La confianza requiere integridad.
Local-first: Toda la funcionalidad principal funciona sin conexión de red.
Paneles portátiles: Las exportaciones HTML son siempre de un solo archivo; no se requiere servidor para verlas.

Verificación

Antes de publicar una nueva versión, verifica el servidor con MCP Inspector para confirmar que todas las herramientas están expuestas correctamente y que el protocolo de enlace se realiza con éxito.

Interfaz interactiva (abre el navegador):

npm run build && npm run inspect

Modo CLI (scriptado / apto 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

Ejecuta antes de publicar para detectar regresiones en el registro de herramientas y el inicio del runtime.

Contribuciones

Consulta CONTRIBUTING.md para las pautas completas de contribución.

npm install && npm test

Registro y Marketplace de MCP

Este plugin está disponible en:

Busca mcp-agent-trace-inspector.

MCP Agent Trace Inspector

Documentación

MCP Agent Trace Inspector

Características principales

¿Por qué esto en lugar de LangSmith / AgentOps?

Avisos

Requisitos

Primeros pasos

Configuración del cliente MCP

Tu primer prompt

Herramientas

Ciclo de vida de traces (3 herramientas)

Inspección (4 herramientas)

Exportación (3 herramientas)

Operaciones (3 herramientas)

Configuración

--db / --db-path

--retention-days

--pricing-table

--no-token-count

Principios de diseño

Verificación

Contribuciones

Registro y Marketplace de MCP

`--db` / `--db-path`

`--retention-days`

`--pricing-table`

`--no-token-count`