mcp-context-inspector

Un servidor MCP plug-and-play + grabador de métricas de ejecución para cualquier agente que llame a herramientas. Apunta el bucle de tu agente a record_session(prompt, model_id, loop_result) después de cada ejecución y esto te ofrece, de forma gratuita:

• Un verdadero servidor MCP (HTTP transmisible) al que puede conectarse cualquier cliente MCP — Claude Desktop, Cursor, tu propia interfaz de chat — que expone 7 herramientas de solo lectura sobre el historial de sesiones, costes, métricas de tokens/herramientas, y...

• El Explorador de la Ventana de Contexto — transparencia total sobre qué entró exactamente en la ventana de contexto del modelo, bloque por bloque, con recuentos de tokens honestos (estimados y etiquetados explícitamente), una barra segmentada proporcional y un panel de detalle que se expande al hacer clic por cada bloque:

  

  (captura de pantalla de la interfaz de chat de referencia construida junto con esto — sre-investigation-agent; el panel superior es lo que cualquier cliente MCP obtiene al consultar get_context_timeline.)

La mayoría de las herramientas de observabilidad de agentes te vuelven a mostrar datos que tu propia interfaz ya mostraba. Esta te muestra algo que normalmente no puedes ver en absoluto: el prompt del sistema frente a las especificaciones de las herramientas, el razonamiento, la llamada/resultado de la herramienta, la respuesta final, en el orden en que realmente entraron en el contexto, con un total de tokens acumulados frente a la ventana de contexto real del modelo — y cuáles de esos bloques son visibles para el usuario final frente a los que son sobrecarga invisible.

Instalar

uv add mcp-context-inspector   # or: pip install mcp-context-inspector
# while co-developing locally against an editable checkout:
uv add --editable ../mcp-context-inspector

Related MCP server: ai-usage-metrics-mcp

Conéctalo a tu agente

from metrics import store

session_id = store.record_session(prompt, model_id, loop_result)

loop_result es lo que sea que devuelva el bucle de tu agente — este paquete solo necesita que tenga el siguiente aspecto:

{
    "trace": [{"tool": "...", "args": {...}, "status": "ok"}, ...],
    "turns": [{"input_tokens": int, "output_tokens": int, "latency_ms": int}, ...],
    "input_tokens": int, "output_tokens": int, "total_tokens": int, "latency_ms": int,
    "context_blocks": [   # optional — omit and you just lose the Explorer, nothing crashes
        {"category": "system", "label": "...", "char_count": int, "token_estimate": int, "turn_n": int | None},
        ...
    ],
}

Categorías de context_blocks: system, tools, user, reasoning, thinking, tool_call, tool_result (opcionalmente lleva una clave "status" para codificar fallos por colores), answer.

Ejecutar el servidor

uv run python -m mcp_server.server

Si no se establece MCP_AUTH_TOKEN → genera e imprime uno al iniciar, el mismo modelo de confianza que el token impreso de un servidor Jupyter. Establécelo tú mismo para obtener un valor estable entre reinicios. Apunta cualquier cliente MCP a http://127.0.0.1:8787/mcp con Authorization: Bearer <token>.

Backends de almacenamiento

STORAGE_BACKEND=sqlite (por defecto, desarrollo local — data/metrics.db) o STORAGE_BACKEND=dynamodb (establece METRICS_TABLE/AWS_REGION) — las mismas firmas de función en ambos casos, los llamadores nunca saben cuál está activo.

Las 7 herramientas MCP

get_session_metrics, get_token_breakdown, get_tool_metrics, get_agent_trace, get_cost_estimate, get_recent_sessions, get_context_timeline. También se exponen equivalentes REST simples bajo /api/* — una alternativa de depuración compatible con curl, que llama a las mismas funciones subyacentes de metrics/store.py.

Repositorios relacionados

sre-investigation-agent — la interfaz de chat de referencia + agente Bedrock del cual se extrajo este paquete y con el que se desarrolla conjuntamente.