What Tollbooth is
A paywall layer for MCP servers, built on a measurement of whether agents come back.
An AI agent calls a paid tool. The tool returns a payment challenge with a checkout URL. A human pays. The agent retries with the handle it was given, and the tool runs. Tollbooth is the library that does the middle of that: the challenge, the handle, the entitlement, and the settlement.
The problem
Most work on paid MCP tools assumes the agentholds a wallet and pays without a human. That is a coherent design, and it is the wrong one for most real deployments today: it means provisioning agents with funds, and it removes the human from a spending decision — which is precisely what MCP’s own security principles insist on.
The other shape — a human pays out of band, the agent resumes — rests on one assumption no protocol guarantees: that the agent comes back. Nothing in MCP promises a model will retry a tool after the user says they paid. So before building anything, we measured it.
In 71 blind trials, agents retried 95–100% of the time with structured and text challenges, and 0% with URL-mode elicitation.measured · 2026-09-07 The results page has the full table, the sample sizes, and what is still unmeasured.
The shape of the answer
- Return immediately, never block. A human paying is a 30-second-to-minutes operation; MCP clients time out at 60 seconds and a server cannot extend that. See how it works.
- Mint your own handle. MCP has no stable caller identity, so Tollbooth issues one and the agent carries it back as a tool argument — which is what the specification itself now prescribes for cross-call state.
- One model, three pricing units. Per-call, credit packs and time passes are one record with different nulls. See pricing units.
- Settle directly to the tool author.Tollbooth never holds anyone else’s revenue. The payment API it builds on has no way to send money onward, so there is nothing to hold and nothing to trust it with.design property
What it is not
- Not a hosted service. It is a library you run on your own server.
- Not an x402 implementation. It is the human-in-the-loop complement to agent-pays designs, not a competitor to them.
- Not published to npm yet. Everything here is built from the repository.
Packages
@tollbooth/core— the entitlement model. No payment provider, no MCP. Enforced in CI.@tollbooth/mcp—withPaywall,paidTool, the challenge renderers.@tollbooth/moove— the Moove payment binding.@tollbooth/store-sqlite— durable, zero-config. The library default.@tollbooth/store-postgres— for deployment; built for Neon.@tollbooth/store-conformance— the suite every store must pass.