Skip to main content

ctx-capture

See exactly what your LLM agent saw, at any step, byte-for-byte.

An MCP server for context-window observability. It captures the exact model input at every step of an agent run — including what a tool actually returned versus what got inserted into the next call after truncation — and lets any MCP client query it directly.

Agent failures are usually context failures, not reasoning failures: a tool result got truncated before it reached the model, a token budget overflowed and the framework quietly cut messages from the middle, a retry duplicated a call the model never saw resolve. Answering "what did the model actually see at step 12" today means archaeology across app logs, framework debug output, and provider dashboards. ctx-capture exists so that question has a direct answer.

Features

  • Byte-exact per-step capture — the exact provider-native message array as sent, not a reshaped/normalized approximation.
  • Pre- and post-truncation tool results — result_as_returned vs. result_as_inserted, so truncation is detectable, not just guessed at.
  • Two capture paths: OpenAI-compatible chat.completions clients and Anthropic's Messages API, both duck-typed (no hard SDK dependency) and both gated by the same fidelity test.
  • 5 MCP tools + 2 resources — list_traces, get_step_context, diff_step_contexts, find_context_anomalies, get_token_accounting, plus trace:// resources for browsing clients. All 5 tools declare outputSchema and return structuredContent.
  • Size-capped, paginated responses — every tool response is bounded (default 50 KB); an oversized payload gets a resource_uri pointer instead of ever blowing up a client's context.
  • SQLite by default, zero external dependency — pip install ctx-capture gives you a working MCP server with nothing else to stand up.
  • CI-blocking fidelity test — the schema's acceptance test, not an optional check: captured messages must be byte-identical, after canonical JSON serialization, to what actually left application code.

Setup

pip install ctx-capture
# or, without installing: uvx ctx-capture --db my_agent.db

Run the server (SQLite-backed, zero config):

python -m ctx_capture.mcp --db my_agent.db

Point an MCP client at it — e.g. Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "ctx-capture": {
      "command": "ctx-capture",
      "args": ["--db", "/absolute/path/to/my_agent.db"]
    }
  }
}

Instrument your agent — a few lines, either capture path:

from ctx_capture.capture import TraceRecorder
from ctx_capture.storage import SQLiteTraceRepository

recorder = TraceRecorder(agent_name="my-agent")

# OpenAI-compatible client — call sites unchanged
client = recorder.wrap_client(my_openai_compatible_client)

# ...or an Anthropic client — call sites unchanged
client = recorder.wrap_anthropic_client(my_anthropic_client)

recorder.begin_step()
response = client.chat.completions.create(model="...", messages=messages)  # or client.messages.create(...)
recorder.end_step()

SQLiteTraceRepository("my_agent.db").save(recorder.trace)

Then, from your MCP client: "list recent traces for my-agent" or "show me exactly what the model saw at step 12" — the client calls list_traces / get_step_context for you.

For a shared/remote deployment: ctx-capture --transport http --port 8000 --bearer-token <token> (see docs/DESIGN.md § Transport for why stdio is the default and HTTP is opt-in).

Tool reference

Tool Answers
list_traces(agent_name?, since?, until?, has_anomalies?, tags?, limit?, cursor?) "What traces have been captured?" — cursor-paginated.
get_step_context(trace_id, step_index, max_bytes?, cursor?) "What did the model see at step N, exactly?" — the byte-exact reconstructed input.
diff_step_contexts(trace_id, step_a, step_b) "What changed in the model's context between two steps?"
find_context_anomalies(trace_id, types?) "Where did something go wrong?" — truncations, budget overflows, dropped messages, tool-result mismatches.
get_token_accounting(trace_id, group_by?) "Where did the tokens/cost go?" — grouped by step, tool, or role.

Plus 2 resources for browsing clients: trace://{trace_id} (metadata + step index) and trace://{trace_id}/step/{step_index} (full, unpaginated step detail).

The fidelity test

The project's one non-negotiable test, CI-blocking forever (tests/test_fidelity.py, tests/test_fidelity_anthropic.py): capture a running agent's model input, reconstruct it from storage, and assert the reconstructed messages array is byte-identical, after canonical JSON serialization, to what an independent observation point saw actually leave application code. If this test can't pass, the schema has failed at the one thing it exists to do.

Capture overhead is measured, not assumed: ~0.017ms added per instrumented model call (in-process benchmark, wrapper only — see docs/RESULTS.md, reproduce with python scripts/bench_overhead.py).

ctx-capture vs. Langfuse / LangSmith

ctx-capture Langfuse / LangSmith
Core question "What did the model see, byte-for-byte, at step N?" "What happened across this run?"
Fidelity Provider-native messages captured verbatim; tool results captured both pre- and post-truncation Traces are typically reshaped for display; framework-level truncation is usually invisible
Interface MCP tools/resources — built for an agent or MCP client to query directly Web dashboard + SDK — built for a human browsing a UI
Evals Not a goal (see Non-goals) Core feature
Dashboards/UI None — MCP clients are the UI Mature, first-class
Multi-agent trace stitching Not in v1 Yes
Storage SQLite (zero-dep) or Postgres, self-hosted Hosted or self-hosted, Postgres-backed service

Use Langfuse/LangSmith for broad observability, evals, cost dashboards, and team-wide trace review. Use ctx-capture when you need to prove, precisely, what one model call actually saw — usually while debugging a specific failure, from inside an MCP-capable client.

Non-goals

  • No dashboards/UI — MCP clients are the UI; we're not rebuilding Langfuse's trace viewer.
  • No eval features — evals are a mature, separate category with a different workflow.
  • No multi-agent trace stitching in v1 — single-agent step fidelity first.
  • No prompt management — that's a build-time concern; this is runtime observability.

See docs/DESIGN.md § Non-goals for the reasoning behind each.

Schema stability

Every trace is written with a pinned schema_version. Within a major version, changes are additive-only — new optional fields, never a repurposed or removed one — so any 1.x reader can read any 1.x trace. A breaking change requires a major version bump and a migration script; servers refuse (not silently coerce) traces with an unsupported major version. See docs/DESIGN.md § The schema for the full schema and versioning rationale.

Roadmap

  • OTel span-ingestion adapter — an additive way to bring in traces from OTel GenAI instrumentation, without making it the primary (lower-fidelity) capture path.
  • Redaction hook — an opt-in redact(message) -> message hook at capture time. Not yet built; until it is, treat captured trace data as sensitive by default (it faithfully contains whatever the agent saw, PII/secrets included).
  • Postgres backend — the TraceRepository interface is ready for it; the implementation isn't written yet.
  • OAuth for HTTP transport — the current HTTP auth is a static bearer token, which is the minimum viable gate, not the final answer for multi-tenant deployments.

License

MIT — see LICENSE.

Metadata

Release files for ctx-capture 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ctx-capture 0.2.0
File Size Uploaded Provenance Actions
ctx_capture-0.2.0.tar.gz 28.4 kB With provenance Details for ctx_capture-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ctx-capture 0.2.0
File Interpreter ABI Platform Actions
ctx_capture-0.2.0-py3-none-any.whl Python 3 none any Details for ctx_capture-0.2.0-py3-none-any.whl

Total release size: 53.2 kB

Release files / ctx_capture-0.2.0.tar.gz

Download URL ctx_capture-0.2.0.tar.gz
Size 28.4 kB
Tags Source
SHA-256 checksum
How to use checksums
3d061ac20956e7d1af2351753c48c9de48b92ea369e4a6ae7f2e558166fa2c87
BLAKE2b-256 checksum
How to use checksums
8cad1e60a487a881a94e67a0b02e312159e2b757c808655affc9945792d58b26
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.

Transparency log

Release files / ctx_capture-0.2.0-py3-none-any.whl

Download URL ctx_capture-0.2.0-py3-none-any.whl
Size 24.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dff003c00910be660e502e0a7102f805d6072eaf85f02e0659df80d70937386c
BLAKE2b-256 checksum
How to use checksums
87b4aa8c56d49ac7888fa7bc56f111af2eea95cb06be5c27f2cfd1928bd2c30f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.

Transparency log

Security for ctx-capture 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ctx_capture-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page