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, with the same wire format as the proxy and 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. The Python package needs 3.11+. There is a TypeScript SDK too, @goodtiming/baton-sdk on npm, which takes the same DSN and emits the same events; everything on this page applies to both unless it says otherwise.

Install

Quote the extras. zsh, the default shell on macOS, treats square brackets as a pattern and stops with no matches found before pip runs.

Quickstart

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

The following diagram illustrates where the SDK runs inside your MCP server:

• No second process. The SDK is a library inside your server, so there is nothing extra to deploy, supervise or keep alive.
• Capture is at the transport boundary: the tool name, params, result and error that crossed MCP. The SDK does not reach into your logs or your database.
• The sink is yours to choose, and it is the only thing that leaves the process.

from mcp.server.mcpserver import MCPServer
from baton import install_baton

mcp = MCPServer("Acme Knowledge Base")
install_baton(mcp, dsn="https://baton_pk_...@baton.goodtiming.ai/ten_.../srv-...")

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

from mcp.server.fastmcp import FastMCP
from baton import install_baton

mcp = FastMCP("Acme Knowledge Base")
install_baton(mcp, dsn="https://baton_pk_...@baton.goodtiming.ai/ten_.../srv-...")

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

from fastmcp import FastMCP
from baton import install_baton

mcp = FastMCP("Acme Knowledge Base")
install_baton(mcp, dsn="https://baton_pk_...@baton.goodtiming.ai/ten_.../srv-...")

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

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { withBaton } from "@goodtiming/baton-sdk";

const server = new McpServer({ name: "acme-knowledge-base", version: "1.0.0" });
withBaton(server, {
  dsn: "https://baton_pk_...@baton.goodtiming.ai/ten_.../srv-...",
});

That string is the whole configuration. It is the DSN for one server, and it carries four things: a publishable key (baton_pk_…), the host events go to, your workspace id (ten_…) and the server's id (srv-…). The SDK reads all four and builds the sink itself.

install_baton works out which library your server comes from, and raises TypeError before changing anything if the object is not an MCP server it supports. Tools registered before and after the call are both captured. It adds one tool to your server, named after it: a server called "Acme Knowledge Base" gets acme-knowledge-base_annotate.

Getting a DSN

Sign in at baton.goodtiming.ai/account and press Add a server, with a name if you want one. The page shows the new DSN with a Copy button, and every server's DSN stays listed under Publishable keys. The setup agent makes one for you when it wires up a server.

We assign the server id and it never changes. The name is a label on /account and in your workspace picker, and you can rename it there. A publishable key can only write events, and only for the server its DSN names, so it is safe in your source.

Where the DSN goes

A server you distribute, meaning a stdio server started on your user's machine, takes the DSN in source, as above. An MCP client starts a stdio server with a fixed allowlist of environment variables (six names on macOS and Linux) plus whatever the user wrote in their own client config, so a value in your .env never reaches it.

A server you host can read it from the environment. Set BATON_DSN and pass nothing:

install_baton(mcp)  # reads BATON_DSN

An explicit dsn= wins over BATON_DSN, and either one wins over BATON_VENDOR_ID and BATON_TENANT_ID, so a new DSN is never overridden by values an earlier install left in the environment.

Without a DSN

To send to your own collector, or to try the SDK before you have a key, name the parts. Leave out sink and events go to stderr as JSON Lines.

import os
from baton import install_baton, VendorConfig
from baton.sinks import HttpSink

install_baton(mcp, VendorConfig(
    vendor_id="acme-kb",
    tenant_id="acme",
    vendor_display_name="Acme Knowledge Base",
    sink=HttpSink("https://collector.example.com", api_key=os.environ["COLLECTOR_KEY"]),
))

vendor_id names the server and tenant_id names the account the collector authenticates. One account holds many servers, so giving both the same value merges every server in it into one. HttpSink posts to {url}/v0/events with the key as a bearer token.

A VendorConfig can carry a DSN too, as VendorConfig(dsn=…, scrubber=…), when you want a DSN and other settings. Passing a DSN alongside vendor_id, tenant_id or sink raises, because the DSN already sets them.

Configuration

Keyword-only. With a DSN, every other field is optional.

Identity

Baton names the person behind a call only when you tell it who that is. You pass one function, resolve_principal. It gets the call's headers, _meta, tool name, arguments and the verified token's claims, and returns a Principal or None. The SDK sends what the function returns and does nothing else to it: no hashing, no key, no guessing.

If your server runs OAuth, two ready-made hooks cover it. Pass one as it is:

from baton import install_baton, VendorConfig, principal_from_oauth_email

install_baton(mcp, VendorConfig(
    dsn="https://baton_pk_...@baton.goodtiming.ai/ten_.../srv-...",
    resolve_principal=principal_from_oauth_email,   # or principal_from_oauth_sub
))

principal_from_oauth_email uses the token's email claim as the id and the part before @ as the name your dashboard shows. principal_from_oauth_sub uses the token's subject. Both return None when the claim is missing. A token exists only on HTTP with auth configured.

For anything else, such as a gateway header, an argument or a stdio login, write your own. It is a few lines:

from baton import Principal

def resolve(ctx):
    employee = (ctx.headers or {}).get("x-forwarded-user")
    if not employee:
        return None
    return Principal(principal_id=employee, display_name=employee.split("@")[0])

The id you return is stored by the collector as it is. Your function decides what is safe to send. If real identities must not leave your side, hash the id in the function and say so:

import hashlib, hmac, os
from baton import Principal

KEY = os.environ["MY_ID_HASH_KEY"].encode()

def resolve(ctx):
    sub = (ctx.claims or {}).get("sub")
    if not sub:
        return None
    digest = hmac.new(KEY, sub.encode(), hashlib.sha256).hexdigest()
    return Principal(principal_id=digest, form="hashed")

A hook that raises, or returns nothing usable, costs that event its person and nothing else: the tool call and the event are unaffected. The two ready-made hooks are short and are the best examples to copy from: Python, TypeScript.

Sinks

from baton import install_baton, VendorConfig
from baton.sinks import StdoutSink, FileSink, MultiSink

# development: stderr and a file
install_baton(mcp, VendorConfig(
    vendor_id="acme-kb",
    vendor_display_name="Acme Knowledge Base",
    sink=MultiSink([StdoutSink(), FileSink("./events.jsonl")]),
))

Turning capture off

Set BATON_DISABLED=1 in the environment of the process that runs the server, and the SDK installs nothing: no wrapped tools, no annotation tool, no change to the server instructions, no collector connection, no background thread. The server runs as it would without the install_baton line. The SDK reads the variable once at startup, never writes to stdout, and never stops the server from starting, even with a config it would otherwise refuse. Any value other than empty, 0, false, no or off turns it on.

The switch belongs to whoever runs the server.

• A server you distribute runs on your user's machine, so the switch is theirs. It goes in the env block for your server in their MCP client's config file, not in their shell: the client passes the server a fixed allowlist of environment variables, and an exported BATON_DISABLED is not on it.
• A server you host runs on your machine, so the switch is yours. Your users cannot set it, and there is no per-user opt-out.

{
  "mcpServers": {
    "acme-knowledge-base": {
      "command": "acme-kb-mcp",
      "env": { "BATON_DISABLED": "1" }
    }
  }
}

Library API

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

The following diagram illustrates where the SDK sits on the library path:

• Your API is untouched. Baton lives in the Skill that calls it, not behind it, so nothing ships on the API side.
• One client.trace(...) per call, inside one client.session(...) per request, is the whole integration; the events it emits are the same envelope the MCP path emits.
• Use this path when you ship a Skill rather than an MCP server.

Sync (Client)

from baton import Client, Principal

client = Client(dsn="https://baton_pk_...@baton.goodtiming.ai/ten_.../srv-...")

with client.session(
    session_id=request.conversation_id,           # optional: your own id for the conversation
    principal=Principal(principal_id=user.id),    # optional: who is calling
    client_info={"name": "claude-code", "version": "2.1"},  # optional: which app is calling
    headers=request.headers,                      # optional: only User-Agent and X-Anthropic-Client are kept
):
    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(what_happened="asked for a CSV export; no endpoint returns one", tool_name="none")

client.close()  # or: with Client(dsn=...) as client:

Open one client.session(...) per request or conversation. Every trace() and annotate() inside it shares its session, principal and client. A call outside any block gets a session of its own, so it does not join the others. Pass client_info or the request's headers when your request says which app the agent runs in; with neither, your dashboard shows "app not reported".

Async (AsyncClient)

from baton import AsyncClient

async with AsyncClient(dsn="https://baton_pk_...@baton.goodtiming.ai/ten_.../srv-...") as client:
    with client.session(session_id=request.conversation_id):
        async with client.trace(tool_name="...", intent="...") as trace:
            response = await vendor_client.chat.completions.create(...)
            trace.observed(response)

Both take the same keyword arguments: dsn, or vendor_id, tenant_id and sink without one. Both read BATON_DSN when no DSN is passed. On both, session() is a plain with block.

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(what_happened="search returned 429 with no retry-after", tool_name="search", suggested_improvement="add retry-after on 429s")

A report says what went wrong in its own words. The collector assigns its group; there is no category to pick. Name the tool the report is about, or pass tool_name="none" when no tool exists for what was asked.

Choosing paths

TypeScript

The same SDK for Node. @goodtiming/baton-sdk emits the same envelope as the Python package to the same sinks, so a workspace can run both and the Console never learns which one produced an event. Node 20+.

npm install @goodtiming/baton-sdk

Your MCP server is the argument, as in Python. Both major versions of the official TypeScript MCP SDK are supported and both are optional peer dependencies, so you install whichever one you already use, either @modelcontextprotocol/sdk 1.x or @modelcontextprotocol/server 2.x, and nothing else.

import { McpServer } from "@modelcontextprotocol/server";
import { withBaton } from "@goodtiming/baton-sdk";

const server = new McpServer({ name: "acme-knowledge-base", version: "1.0.0" });

withBaton(server, {
  dsn: "https://baton_pk_...@baton.goodtiming.ai/ten_.../srv-...",
});

Config fields are the Python names in camelCase (vendorId, tenantId, vendorDisplayName, intentParamMode, scrubber), and a dsn replaces the first three exactly as it does in Python. Tools registered before or after withBaton are both captured, and so are tools added or removed later.

Identity works as in Python: pass resolvePrincipal, which returns { principalId, displayName?, form? } or null. principalFromOAuthEmail and principalFromOAuthSub ship ready-made and read the token's claims from authInfo.extra. See Identity.

import { withBaton, principalFromOAuthEmail } from "@goodtiming/baton-sdk";

withBaton(server, {
  dsn: "https://baton_pk_...@baton.goodtiming.ai/ten_.../srv-...",
  resolvePrincipal: principalFromOAuthEmail,
});

Without MCP

The Library API is here too, as Client. The block and the call take callbacks instead of with: client.session(options, fn) and client.trace(options, fn). The option names are the Python names in camelCase. Put one trace() where every tool call passes through, such as a middleware, and every tool is covered.

import { Client } from "@goodtiming/baton-sdk";

const baton = new Client({ dsn: process.env.BATON_DSN });

app.use((req, res, next) =>
  baton.session({ sessionId: req.get("x-conversation-id"), headers: req.headers }, () =>
    baton.trace({ toolName: req.path, params: req.body }, () => next()),
  ),
);

A callback can be sync or async. Its return value is recorded as the result, and a throw is recorded and passed on unchanged. client.wrap(toolName, fn) traces a function on every call, for code with no single place to put trace().

What it captures

The same three intent parameters, the same annotation tool, the same surface_snapshot, and the same events. intentParamMode defaults to "required", which advertises all three in each tool's required list and never enforces them. Measured identical to the Python SDK and the proxy on the currently published versions.

PII scrubbing is on by default here too, a rule-for-rule port of Python's ruleset. Pass identityScrub to opt out, or your own (value: unknown) => unknown. Read what it does and does not catch before relying on it.

What is not here yet

Stated so you find out now rather than later. None of it blocks the paths above.

• Only StdoutSink and HttpSink. FileSink and MultiSink are deferred; the Python package has all four.
• Only the high-level McpServer. The low-level Server is not wrapped.
• Intent parameters need a Zod schema. On the 2.x SDK a tool registered with a non-Zod standard schema is still wrapped and still emits tool_call_*; it just advertises no intent parameters.
• The per-request createMcpHandler shape is unscoped. It builds a fresh server per request, which would make the session id and the snapshot dedup request-lifetime state.

Wire compatibility

This is a tested property, not an intention. Both SDKs are checked against baton-spec, a neutral schema repo: every event type is validated against the shared JSON Schema, and the TypeScript emitter is diffed field-by-field against captured Python output for the same scenario. Envelope and payload keys must match exactly; values match except for ids, timestamps, timings and the genuinely language-specific fields.

PII scrubbing

Scrubbing is on by default. baton.scrub.Scrubber walks every event payload before it reaches the sink and redacts email addresses, Bearer tokens of 16 or more characters, sk- keys, AKIA access keys, JWTs, North American phone numbers, and card numbers that pass a Luhn check. It also redacts the whole value of any field named email, phone, ssn, api_key, token, secret, password or user_name.

It matches patterns. It does not find every piece of personal data. {"name": "Jane Doe", "address": "12 Elm St"} passes through unchanged, and a card number written with spaces or hyphens is not caught. Decide what your tools put in their arguments and results with that in mind.

To turn it off:

from baton import install_baton, VendorConfig
from baton.scrub import identity_scrub

install_baton(mcp, VendorConfig(dsn="https://baton_pk_...@baton.goodtiming.ai/ten_.../srv-...", scrubber=identity_scrub))

capture a whole fleet at once

Overview

For fleets of MCP servers. The other two paths instrument one server at a time: the SDK goes inside a server you own, the proxy wraps a server you do not. This one captures at the gateway itself, so every server behind it is covered at once, and neither your clients nor your backend servers change.

Baton runs as a processor beside your gateway, on the gateway's external-processor hook for MCP. Traffic still flows client to gateway to server. Baton sees the MCP messages as they pass and never becomes a hop in the path: it is not a subprocess wrap and not an HTTP bridge.

The following diagram illustrates where Baton sits relative to your gateway:

• Your gateway keeps the traffic. Client to gateway to server is unchanged; Baton is not inserted between any two of them.
• The hook hands Baton a copy. The external-processor call is what Baton sees. Configure that hook fail-open and a Baton outage costs you the event, not the call.
• Every server behind the gateway is covered at once, and none of them ships a change.

This is the path that reaches surfaces with no code to instrument. A client behind the gateway is captured without anyone shipping a change to it.

Quickstart

There is no package to install yet. The proxy and the SDK are published and you can start with either one today; the gateway processor ships with a runbook for your platform team instead, and we set it up with you. Talk to us and we will size it against your gateway.

Configuration

Two pieces: one hook in your gateway's own policy, pointed at the processor and set to see both the request and the response of each tool call along with its session id, and the same handful of environment variables the proxy reads.

Nothing has to leave your walls. Point the sink at your own storage and the Console never sees an event.

Identity

This path resolves the caller from a request header, and which header is configuration rather than code. The value is hashed inside the processor and the raw identity never leaves your network, exactly as on the other two paths.

It needs two settings, and both matter: the header, which your gateway must pass on every call, and the hashing key, BATON_PRINCIPAL_ID_HMAC_KEY. A call without the header is captured with no caller, and nothing reports it. Without the key, the processor logs one warning and sends every event with no caller.

What it captures

Two parameters are added to the tool list the gateway returns: the agent's goal, and the result it expects. The agent fills them in on the next call. Baton reads them off that call and strips them before the request reaches your server, so your tool schemas and your handlers are unchanged and your customers never see them.

The events are the same wire format the other two paths emit, so one Console reads all three. A response carries no request id, so the gateway passes the session id to the processor on both halves of each call, and results pair within a session in the order calls were made. Pairing is exact while a session's calls complete in order. Calls running at the same time inside one session can pair with the wrong request, and a call with no session id gets no result event.

Scrubbing runs in the processor before any sink sees an event, with the same patterns as the SDK.

Trust & security

sample friction yourself

Overview

baton-proxy wraps an MCP server and captures friction events. From Claude's perspective it is the MCP server; the real server is either its child process or the endpoint it forwards to. Your server receives the arguments it would have received unwrapped: the proxy adds three intent parameters to each tool's advertised schema and strips them from every call before forwarding.

Two upstream forms. A stdio server is named after -- and run as a subprocess; a remote Streamable-HTTP server is named with --url, with BATON_UPSTREAM_AUTH_TOKEN sent upstream as a bearer token. They are mutually exclusive.

uvx baton-proxy -- python server.py               # stdio, as a subprocess
uvx baton-proxy --url "https://mcp.example.com/mcp"  # remote, as a bridge

The following diagram illustrates how the proxy sits between Claude and your server:

• The proxy is the server, as far as Claude is concerned. Your real server runs as its child process and receives the arguments it would have received unwrapped.
• Green marks what Baton owns, here the proxy and the Console. Everything neutral is yours or your client's, and none of it changes.
• Three sinks, one event. The same envelope goes to stderr, a file, and an https:// collector; which ones are live is configuration.

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.

Quickstart

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, just ask Claude. It is told where the file is,
// and every line carries a session_id it can filter on:
"What went wrong in 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"
  }
}

scan

Preview friction on a server you already have configured, with no permanent install and 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, so nothing leaves your machine.

Configuration

All knobs are environment variables. Every one has a default, so no config file is needed.

The three rungs

Remote servers

The proxy also fronts a remote HTTPS MCP server over the Streamable HTTP transport, instead of spawning a subprocess. It stays stdio-facing to Claude and forwards each message as an HTTP POST, streaming the JSON or SSE response back. Injection, emission and correlation are the same code as the subprocess path.

{
  "command": "baton-proxy",
  "args": ["--url", "https://mcp.vendor.example.com/mcp"],
  "env": { "BATON_UPSTREAM_AUTH_TOKEN": "..." }
}

--url and the -- <command> form are mutually exclusive.

Injected tools

The proxy adds baton_annotate to the upstream server's tool list during the MCP handshake. The upstream server never sees it. When the proxy writes events to a local file, the instructions it appends name that file's path, so Claude can read it and explain what went wrong.

What it captures

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 failure the server returned rather than raised — MCP files one as a successful 200 whose body sets isError — 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_error","payload":{"tool_name":"run_sql","error_type":"tool_error","error_body":"foreign keys are not supported","result":{"content":[{"type":"text","text":"foreign keys are not supported"}],"isError":true},"duration_ms":412}}
{"event_type":"annotation","payload":{"what_happened":"asked run_sql to add a foreign key; it answered that foreign keys are not supported","intent":"add a foreign key so an order can't reference a missing customer","suggested_improvement":"list unsupported DDL in the tool description","tool_name":"run_sql"}}

Intent parameters

This is how the proxy captures why a call was made, not just what happened. At tools/list it adds three string parameters to every upstream tool's advertised schema. The agent fills them in as it composes each call, and the proxy strips them at tools/call before forwarding.

In the default mode, all three are advertised in each tool's required list. That is advertisement only: a call that omits one is served exactly as it would be unwrapped, and the matching field is simply null. From proxy 0.6.18, a wrapped tool's schema lists ["customer", "user_goal", "expected_result", "overall_task"] as required where the unwrapped one listed ["customer"].

A parameter description reaches the model at the moment it composes the call, on every client. Some clients drop InitializeResult.instructions entirely, so instructions alone are not a reliable channel. A tool that already declares a parameter of that name is left alone: its value is forwarded untouched and never read as intent.

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.
• Scrubbed on your machine. Same rules as the SDK, applied before any event leaves. PII scrubbing →