Docs

What is Baton

Baton is actionable product analytics for MCP servers. When a customer's agent calls your server and your API can't meet the request, you often get a 200 with an empty body or a vague error — the customer's intent vanishes with no ticket and no trace. Baton captures that friction at the moment it happens: what the customer was trying to do, the call the agent made, what it expected, and what it got.

You instrument your server once. Whatever agent your customers use — Claude, Cursor, ChatGPT — keeps working exactly as before.

Test, deploy, act

Most teams move through three stages. The first two are free and open source and capture the signal; the third is the paid Console, where you act on it. You only need one of the two capture paths.

How it fits together

The proxy and the SDK emit the exact same events to a sink you choose; the difference is who drives them and where they live. The proxy is you, sampling your own server. The SDK is baked into your server (or your Skill), capturing real customer traffic. Either way, the Baton Console is where that signal becomes a ranked roadmap your team can act on.

Each section has an architecture diagram: the Proxy and SDK pages show how capture works; the Console page shows how it comes together across customers.

Stage 1 · Test  ·  sample friction yourself

Overview

baton-proxy wraps any stdio MCP server and captures friction events. From Claude's perspective it is the MCP server; the real server is its child process. All MCP traffic passes through unchanged.

Per real tool call, three event types are emitted matching the Baton wire format:

Each line in the events file is one JSON object — { event_type, payload }. A silent failure (a 200 that carried an error) lands like this:

{"event_type":"tool_call_start","payload":{"tool_name":"run_sql","params":{"statement":"ALTER TABLE orders ADD CONSTRAINT fk_customer FOREIGN KEY (customer_id) REFERENCES customers(id)"}}}
{"event_type":"tool_call_end","payload":{"tool_name":"run_sql","result":"200 OK — body: \"foreign keys are not supported\"","duration_ms":412}}
{"event_type":"annotation","payload":{"signal_type":"failure","intent":"add a foreign key so an order can't reference a missing customer","suggested_improvement":"reject unsupported DDL with an error instead of a silent 200"}}

Install

For a one-off scan, install nothing — uvx runs it on demand:

uvx baton-proxy scan --config <server-name>

To wrap a server permanently in Claude's config, put baton-proxy on your PATH so the config can invoke it directly:

pipx install baton-proxy

Plain pip install baton-proxy works if you manage your own Python env. Requires Python 3.11+. Currently 0.x — the wire format is stable and additive-only until v1.0; see the releases.

Quick start

Replace your MCP server entry in Claude's config. The only change is wrapping your existing command:

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

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

Restart Claude and drive a few tool calls. Then see what happened:

// In conversation — ask Claude:
"Show me the friction report for this session."

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

To ship events to a Console, 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":       "bk_live_...",
    "BATON_CONSENT_TOKEN": "customer-consented"
  }
}

Configuration

All knobs are environment variables. Every one has a default — no config file needed.

The three rungs

Injected tools

The proxy appends two tools to the upstream server's tool list during the MCP handshake. The upstream server never sees them.

scan

Preview friction on a server you already have configured — no permanent install, no change to your Claude config.

uvx baton-proxy scan --config my-server

scan reads the named entry from ~/.claude.json, reuses its credentials, drives a headless agent, and writes ./baton-report.md. Events are written to a temp file and deleted after the report — nothing leaves your machine.

Trust & security

• Open source, Apache 2.0. github.com/good-timing/baton-proxy
• Fail-open. A Console outage never breaks the MCP pipe. Emission is enqueued on a background thread.
• Outbound-only. The proxy never accepts inbound connections.
• No external dependencies. Pure stdlib — no pydantic, no httpx.
• Credential isolation. BATON_* vars are filtered from the upstream subprocess env.

Stage 2 · Deploy  ·  capture friction from your customers

Overview

baton-sdk is native instrumentation for vendors who control their MCP server source. One call wires up capture, annotation, and sink routing — same wire format as the proxy, no subprocess hop. Because it lives inside what you ship, it captures friction from your real customers, who never have to install anything.

baton-sdk is open source under Apache-2.0; the source lives in the baton repo. Requires Python 3.11+.

Install

MCP integration

The SDK runs in-process inside your server and captures every tool call at the transport boundary — no subprocess, your tools unchanged.

import os
from mcp.server.fastmcp import FastMCP
from baton.integrations.mcp import install_baton, VendorConfig
from baton.sinks import HttpSink

mcp = FastMCP("your-vendor-mcp")
install_baton(mcp, VendorConfig(
    vendor_id="your-vendor",
    vendor_display_name="Your Vendor",
    consent_token=os.environ["BATON_CONSENT_TOKEN"],
    sink=HttpSink(
        url=os.environ["BATON_INGEST_URL"],
        api_key=os.environ["BATON_API_KEY"],
    ),
))

@mcp.tool()
async def your_tool(...): ...

import os
from fastmcp import FastMCP
from baton.integrations.fastmcp import install_baton, VendorConfig
from baton.sinks import HttpSink

mcp = FastMCP("your-vendor-mcp")
install_baton(mcp, VendorConfig(
    vendor_id="your-vendor",
    vendor_display_name="Your Vendor",
    consent_token=os.environ["BATON_CONSENT_TOKEN"],
    sink=HttpSink(
        url=os.environ["BATON_INGEST_URL"],
        api_key=os.environ["BATON_API_KEY"],
    ),
))

@mcp.tool()
async def your_tool(...): ...

Sinks

from baton.sinks import StdoutSink, FileSink, HttpSink, MultiSink

# dev
sink = MultiSink([StdoutSink(), FileSink("./events.jsonl")])

# production
sink = HttpSink(url=os.environ["BATON_INGEST_URL"], api_key=os.environ["BATON_API_KEY"])

Library API

For vendors whose customers reach the API via agent-generated code (Skills pattern). Here Baton lives in the Skill code, not in a server — so it fits vendors who have no MCP server at all.

Sync (Client)

from baton import Client, SignalType
from baton.sinks import HttpSink

client = Client(
    vendor_id="your-vendor",
    consent_token=os.environ["BATON_CONSENT_TOKEN"],
    sink=HttpSink(url=os.environ["BATON_INGEST_URL"], api_key=os.environ["BATON_API_KEY"]),
)

with client.trace(
    tool_name="chat.completions.create",
    intent="summarize the user's question",
    expected_outcome="2-3 sentence answer",
) as trace:
    response = vendor_client.chat.completions.create(...)
    trace.observed(response)

client.annotate(signal_type=SignalType.DEAD_END, suggested_improvement="...")
client.close()  # or: with Client(...) as client:

Async (AsyncClient)

from baton import AsyncClient, SignalType

async with AsyncClient(
    vendor_id="your-vendor",
    consent_token=os.environ["BATON_CONSENT_TOKEN"],
    sink=HttpSink(url=os.environ["BATON_INGEST_URL"], api_key=os.environ["BATON_API_KEY"]),
) as client:
    async with client.trace(tool_name="...", intent="...") as trace:
        response = await vendor_client.chat.completions.create(...)
        trace.observed(response)

Signal types

Eight friction signal types per SPEC §3.1. Stable and additive-only until v1.0.

trace.annotate()

with client.trace(tool_name="search", intent="find docs for X") as trace:
    try:
        result = search_api.query(...)
        trace.observed(result)
    except ApiError as e:
        trace.observed(error=e)
        trace.annotate(signal_type=SignalType.FAILURE, suggested_improvement="add retry-after on 429s")

Choosing paths

PII scrubbing

Scrubbing is on by default. baton.scrub.Scrubber walks every event payload before it reaches the sink and redacts emails, bearer tokens, sk-* keys, JWTs, credit card numbers, phone numbers, and any field named password, token, secret, etc.

To opt out:

from baton.scrub import identity_scrub

install_baton(mcp, VendorConfig(..., scrubber=identity_scrub))

Stage 3 · Act  ·  turn the signal into a roadmap

Overview

The proxy and the SDK capture friction for free. The Baton Console is the hosted, paid tier that collects those events across every customer and every session and turns them into something you can act on. It does two things a single local report can't: it shows the friction across your whole customer base, and it lets your team respond back into the customer's agent.

How it works

Every event your proxy or SDK emits to an https:// sink lands in the Console under your tenant. There it's deduped across customers and ranked into trends, so you see the demand, not one transcript at a time.

Respond & prioritize

Analytics tell you what to build. When something's worth a human right now, the Console closes the loop.

Access & security

The Console is hosted by us and auditable by you. Your data is single-tenant, and every event is logged and inspectable — you can see exactly what each agent sent, when, and why. You define the schema and PII is scrubbed before anything leaves your machine, so what you don't capture can never reach us.

Capturing the signal with the proxy or SDK is free. The Console is the paid tier where you act on it. Talk to us about access →