baton-proxy

Transparent MCP proxy. Wraps a stdio MCP server as a subprocess, or bridges to a remote Streamable-HTTP MCP server (--url); injects an annotation tool and two intent parameters into the handshake, and emits friction events to one or more sinks (stderr, a JSONL file, or a Baton Console).

Zero changes to the underlying MCP server. The proxy is the MCP server from Claude's perspective; the real server is either its child process (stdio) or the endpoint it forwards to (--url).

┌──────────┐      ┌───────────────┐      ┌────────────────────┐
│  Claude  │ ◀──▶ │  baton-proxy  │ ◀──▶ │ your MCP server    │
└──────────┘      └───────┬───────┘      └────────────────────┘
                          │
                          │ async fan-out — pick any subset
                          ▼
   ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
   │  stderr:        │  │  file://        │  │  Baton Console  │
   │  JSONL stream   │  │  JSONL file     │  │  (HTTPS POST)   │
   └─────────────────┘  └─────────────────┘  └─────────────────┘

Trialling Baton inside your company

If someone else has to approve what runs on your machine, start with try/SECURITY.md. It is a review document written to be read before anything is cloned, by a reviewer who never talks to us: what changes on your machine (one MCP config entry), what gets recorded, what the redaction does and does not cover, and how to re-derive every claim here yourself in about a minute.

The trial is the try/ folder — a recipe and a receipt command, not a second product. It installs nothing; the proxy is the source you just reviewed, so the code you read is the code that runs. Events go to a local JSONL file, and whether that file ever leaves your machine is a decision you make at the end.

git clone https://github.com/good-timing/baton-proxy
cd baton-proxy/try && claude

Claude reads the instructions in that folder and walks you through it. Three commands do the work — setup, receipt, uninstall — and the last one restores your original entry at any point, including immediately.

Quick start

pipx install baton-proxy  # or: pip install baton-proxy

pipx installs the CLI into its own isolated venv and puts baton-proxy on your PATH — so Claude's config can invoke it directly without env activation. Plain pip install works if you already manage your own Python env.

Replace your MCP server entry in Claude's config:

// Before
{ "command": "npx", "args": ["@vendor/mcp-server"] }

// After — zero-config: events go to stderr + /tmp/baton-proxy.jsonl
{ "command": "baton-proxy", "args": ["--", "npx", "@vendor/mcp-server"] }

That's the entire install. Start a new Claude session, drive the wrapped server, then either:

• Ask Claude "show me the friction report for this session" — the proxy injects a baton_session_report tool that returns a vendor-shareable markdown report directly in the conversation, or
• cat /tmp/baton-proxy.jsonl to see the raw friction events.

No env vars, no backend, no credentials. The report is a preview of the ticket shape a Baton-instrumented vendor sees in their Console.

To ship events to a Console instead (or in addition), add four env vars:

{
  "command": "baton-proxy",
  "args": ["--", "npx", "@vendor/mcp-server"],
  "env": {
    "BATON_EVENT_SINK":    "https://console.example.com",
    "BATON_TENANT_ID":     "your-tenant",
    "BATON_API_KEY":       "...",
    "BATON_CONSENT_TOKEN": "..."
  }
}

The proxy adds two tools to the upstream server's tool list:

• baton_annotate — Claude calls it (unprompted) when it hits friction; emits an annotation event.
• baton_session_report — Claude calls it (when the customer asks for a report); returns a vendor-shareable markdown summary of the session's friction. Only injected in local-sink installs — vendors using an http(s):// sink (production mode) get a clean tool list; the vendor's Console renders tickets there instead.

And the proxy emits a friction event per real tool call.

Try it in one command: scan

Preview the friction an agent is likely to hit on a server you run — no permanent install, no change to your Claude config:

uvx baton-proxy scan --config github

scan targets a server you've already configured in Claude (by name), reusing that entry's saved credentials. It writes an ephemeral config, drives a headless agent (claude -p, billed to your own auth) through the wrapped server, and renders ./baton-report.md. Everything runs locally — nothing leaves your machine, and you type no secrets. The report is labeled preflight/inferred: it previews likely friction, it's not real-user data (that's what the permanent wrap above captures).

Why --config (and not a raw server command)? A friction report only delivers its insight on a server you actually run — its real tools, its real auth, your real workflows. So scan resolves a configured entry rather than scanning a stranger's server. It reads --config <name> from ~/.claude.json or ./.mcp.json; point at a specific file with --config-file:

uvx baton-proxy scan --config github --config-file ./.mcp.json

Details:

• The resolved entry's credentials (its env, including ${VAR} references) flow to the wrapped server untouched.
• An entry that's already baton-proxy-wrapped is unwrapped automatically, and its BATON_* vars are dropped so the scan session stays local rather than shipping to your real Console.
• Remote/OAuth (http/sse) entries aren't supported yet — scan wraps stdio servers.
• --timeout bounds the run (default 300s; a partial report renders on expiry). --out sets the report path.

What gets emitted

These event types match the Baton wire format:

Each event carries a session id (one per proxy process), monotonic sequence number, and the upstream MCP request's _meta block (for cycle correlation).

The injected baton_annotate tool itself is handled by the proxy; the upstream server never sees it.

Intent parameters

At tools/list the proxy adds two optional string parameters to every upstream tool's advertised schema, and strips them at tools/call before forwarding. Your server receives the arguments it would have received unwrapped.

This is the capture path that survives clients which drop InitializeResult.instructions entirely (observed on Claude Desktop): a parameter description reaches the model at the moment it composes the call. intent_source records where a captured intent came from, and the session's first one also emits a proactive annotation sequenced before its tool_call_start.

A tool that already declares a parameter of one of those names is left alone for that field. Its value is forwarded to the vendor untouched and never read as intent. Injection and stripping are fail-open throughout: an error there forwards the message unmodified rather than failing the call.

Payload scrubbing

Every payload passes through scrub.py in Emitter._enqueue before it reaches any sink, local file included. It is on by default and there is no env var to turn it off.

Redacted by pattern: JWTs, Bearer header values, sk-… API keys, AKIA… AWS access key ids, email addresses, North-American-format phone numbers, and 13–19 digit strings that pass a Luhn check — which catches card numbers and, by design, about 1 in 10 other long digit strings, so the cc count means card-shaped, not card. Redacted by field name regardless of value: email, phone, ssn, api_key, token, secret, password, user_name.

What it does not do, stated plainly because the distinction matters: it targets credentials and personal identifiers, not the substance of the work. Query results, table and column names, document text and row contents are recorded as your server returned them. Values nested more than ten levels deep are passed through untouched (DEPTH_LIMIT), and non-string leaves are not examined.

Per-category counts are available as Emitter.scrub_counts.

Configuration

All knobs are environment variables. Every emission-related one has a default; the zero-config install (no env vars) writes events to stderr + /tmp/baton-proxy.jsonl.

The three rungs

Pick the rung you need; the env-var deltas are the entire difference.

See it locally

After installing ({ "command": "baton-proxy", "args": ["--", "npx", "@vendor/mcp-server"] } in your Claude config) and starting a new Claude session, drive a few tool calls and try either:

Conversational — ask Claude:

Show me the friction report for this session.

Claude calls the injected baton_session_report tool; the proxy returns a markdown report (per-tool breakdown, errored calls with input/error detail, any annotations the model emitted) that Claude relays directly in the conversation.

Raw — inspect the JSONL stream:

cat /tmp/baton-proxy.jsonl | jq -c '{type: .event_type, payload}'

See examples/live-claude-invocation/ for a guided walk-through that also covers the elicitation behaviour of the injected baton_annotate tool.

Sink misconfig fails loudly

The proxy refuses to start when:

• an http(s):// sink is configured but BATON_API_KEY is unset
• an http(s):// sink is configured but BATON_CONSENT_TOKEN is still the placeholder "local"
• an http(s):// sink is configured but BATON_VENDOR_ID is still the placeholder "local"
• the sink URL has an unsupported scheme

These are emitted as proxy startup errors so a misconfigured install never silently drops or silently mistags events.

Trust properties

• Open source, Apache 2.0. Auditable end-to-end.
• Fail-open. Console outage, network issue, or instrumentation bug never breaks the MCP pipe. Tested by tests/test_emitter.py::test_stop_is_clean_when_console_dead and tests/test_injection.py.
• Outbound-only. The proxy never accepts inbound connections. Events go to the configured sink (HTTP POST out for https:// sinks, local file write for file:// sinks); that's the only egress surface.
• Source-side scrubbing, on by default. Credentials and PII patterns are redacted before any sink sees a payload — not a roadmap item. Scope and limits above.
• No deps. Pure stdlib. No pydantic, no httpx, no third-party runtime requirements.
• Emission off the hot path. Event emission is enqueued onto a background thread; the proxy I/O pump does not wait for the POST. End-to-end overhead measurement pending.

Trust model. baton-proxy and the wrapped MCP server run in the same trust domain (same user, vendor's own MCP server). The proxy filters BATON_* from the upstream subprocess env as a least-privilege measure — the upstream has no need for Baton credentials, and accidental leakage paths (debug logging, crash-report env dumps, future plugins) shouldn't see them. This is not a cross-process trust boundary; don't use baton-proxy to instrument an MCP server you don't trust — that's not the threat model the proxy is designed for.

How it works

Two unidirectional pumps:

• client → server: forwards stdin lines to the child process. Intercepts tools/call for baton_annotate (proxy synthesises the response). For every other tools/call, reads and strips the intent parameters, enqueues a tool_call_start event carrying them, and records the request id.
• server → client: forwards child stdout to the client. Modifies the initialize response to append annotation-tool instructions; modifies the tools/list response to append the baton_annotate tool and splice the intent parameters onto every upstream tool's schema, and snapshots the vendor-true surface before those additions. Correlates responses by id to emit tool_call_end / tool_call_error.

A third background thread drains an in-memory queue and delivers events one at a time to the configured sink (HTTP POST for https://, JSONL append for file://). Failed deliveries are logged and dropped — the proxy never retries on the hot path.

Development

git clone https://github.com/good-timing/baton-proxy
cd baton-proxy
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

Related

• baton-sdk — the in-process alternative. Vendors who control their MCP server add install_baton(mcp, ...) instead of subprocess-wrapping. Same wire format, same sinks; tighter integration with one line of vendor code.
• Baton wire protocol — the event envelope, signal taxonomy, and HTTPS contract that both baton-proxy and baton-sdk emit against.

Roadmap

• Static-linked single-binary distribution (PyInstaller, then likely a Go rewrite once distribution shape is set).
• Helm chart for hosted-HTTP MCP servers.
• Hosted-evaluation mode (per-request consent tokens).

License

Apache 2.0. See LICENSE.