mcp-context-inspector

모든 도구 호출 에이전트에 바로 적용할 수 있는 MCP 서버 + 실행 메트릭 레코더입니다. 각 실행 후 에이전트 루프를 record_session(prompt, model_id, loop_result)로 연결하면 다음과 같은 기능을 무료로 제공합니다:

• 실제 MCP 서버(Streamable HTTP) — Claude Desktop, Cursor, 자체 채팅 UI 등 모든 MCP 클라이언트가 연결 가능 — 세션 기록, 비용, 토큰/도구 메트릭에 대한 7개의 읽기 전용 도구를 노출하며...

• Context Window Explorer — 모델의 컨텍스트 윈도우에 실제로 입력된 내용을 블록별로 완전히 투명하게 보여줍니다. 정직한(명시적으로 추정치라고 표시된) 토큰 수, 비례 분할 막대, 블록별 클릭 시 확장되는 세부 패널을 제공합니다:

  

  (이 패키지와 함께 개발된 참조 채팅 UI — sre-investigation-agent의 스크린샷입니다. 위 패널은 MCP 클라이언트가 get_context_timeline을 쿼리할 때 얻는 내용입니다.)

대부분의 에이전트 관측 도구는 자체 UI에 이미 표시된 데이터를 다시 보여줍니다. 이 도구는 일반적으로 전혀 볼 수 없는 것을 보여줍니다: 시스템 프롬프트 대 도구 사양 대 추론 대 도구 호출/결과 대 최종 답변을 실제로 컨텍스트에 입력된 순서대로, 모델의 실제 컨텍스트 윈도우에 대한 누적 토큰 합계와 함께 — 그리고 해당 블록 중 최종 사용자에게 표시되는 것과 보이지 않는 오버헤드가 무엇인지까지 알려줍니다.

설치

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

에이전트에 연결하기

from metrics import store

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

loop_result는 에이전트 루프가 반환하는 모든 값입니다. 이 패키지가 필요로 하는 형식은 다음과 같습니다:

{
    "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},
        ...
    ],
}

context_blocks 카테고리: system, tools, user, reasoning, thinking, tool_call, tool_result (선택적으로 실패 색상 구분을 위한 "status" 키 포함), answer.

서버 실행하기

uv run python -m mcp_server.server

MCP_AUTH_TOKEN이 설정되지 않은 경우 → 시작 시 생성하여 출력합니다. Jupyter 서버의 출력 토큰과 동일한 신뢰 모델입니다. 재시작 간에 안정적인 값을 원하면 직접 설정하세요. http://127.0.0.1:8787/mcp에 Authorization: Bearer <token> 헤더와 함께 MCP 클라이언트를 연결하세요.

스토리지 백엔드

STORAGE_BACKEND=sqlite (기본값, 로컬 개발 — data/metrics.db) 또는 STORAGE_BACKEND=dynamodb (METRICS_TABLE/AWS_REGION 설정) — 두 경우 모두 동일한 함수 시그니처를 사용하므로 호출자는 어떤 백엔드가 활성화되어 있는지 알 필요가 없습니다.

7가지 MCP 도구

get_session_metrics, get_token_breakdown, get_tool_metrics, get_agent_trace, get_cost_estimate, get_recent_sessions, get_context_timeline. 일반 REST 엔드포인트도 /api/* 아래에 노출되어 있습니다. curl 친화적인 디버깅 대안으로, 동일한 기본 metrics/store.py 함수를 호출합니다.

관련 저장소

sre-investigation-agent — 이 패키지가 추출되고 함께 개발된 참조 채팅 UI + Bedrock 에이전트입니다.