Tollbooth Authority MCP server

Tollbooth Authority

The institution that built the infrastructure.

The metaphors in this project are drawn with admiration from The Phantom Tollbooth by Norton Juster, illustrated by Jules Feiffer (1961). Milo, Tock, the Tollbooth, Dictionopolis, and Digitopolis are creations of Mr. Juster's extraordinary imagination. We just built the payment infrastructure.

The Turnpike Authority

Every turnpike has an authority. Not the operators who run the booths, and not the drivers who pay the fares — but the institution that poured the concrete, erected the signs, and stamped the purchase orders.

The Tollbooth Authority is the Massachusetts Turnpike Authority of the Lightning economy. It doesn't operate any toll booths. It doesn't touch operator BTCPay stores. It never sees user payment data. What it does is simpler and more essential:

• It registers operators who want to run toll booths on the turnpike.
• It collects a modest certification fee — 2% of every fare, minimum 10 sats — paid in advance via Lightning.
• It stamps purchase orders — Schnorr-signed Nostr event certificates (kind 30079) that prove an operator has paid their fee before collecting a fare.
• It never touches the fare itself. The operator collects from the user directly.

The Authority's signature is the proof that the turnpike is legitimate. Without the stamp, the toll booth doesn't open.

Architecture

As of v0.9.0, this Authority is an ~80-line thin consumer of the tollbooth-dpyc wheel. Every piece of generic Authority code — onboarding state machine, Schnorr certificate signer, replay tracker, Neon tenant provisioner, and the full 10-tool MCP surface — lives in the wheel's tollbooth.authority package. This repo's server.py supplies only actor-specific configuration: identity name, human-readable instructions, OperatorRuntime construction, and two register_*_tools(mcp, runtime) calls.

# The entire server.py, distilled
from fastmcp import FastMCP
from tollbooth.authority import (
    AUTHORITY_TOOL_REGISTRY,
    OPERATOR_CREDENTIAL_TEMPLATE,
    register_authority_tools,
)
from tollbooth.runtime import OperatorRuntime, register_standard_tools
from tollbooth.tool_identity import STANDARD_IDENTITIES

mcp = FastMCP("tollbooth-authority", instructions="…")
runtime = OperatorRuntime(
    tool_registry={**STANDARD_IDENTITIES, **AUTHORITY_TOOL_REGISTRY},
    vault_source="env",               # Authority arrives with its own Neon
    purchase_mode="auto",             # derive direct/certified from the registry chain
    service_name="Tollbooth Authority",
    ots_enabled=True,
    operator_credential_template=OPERATOR_CREDENTIAL_TEMPLATE,
)
register_standard_tools(mcp, "authority", runtime, ...)
register_authority_tools(mcp, runtime)

Refactor history:

• v0.5.0 introduced OperatorRuntime and delegated standard tools to the wheel — ~1,900 lines → ~970.
• v0.19.0 required+verified proof on every tool that names it; the local verifyoperatorproof helper was promoted to wheel-side tollbooth.identityproof.require_proof.
• v0.21.0 (wheel) promoted 6 supporting modules (onboarding, nostrsigning, replay, tenantprovisioner, rolemigration, settings) from forked Authority code into tollbooth.authority..
• v0.22.0 (wheel) promoted the 10 Authority @tool definitions into registerauthoritytools(mcp, runtime).
• v0.9.0 (this release) deleted the eight now-redundant modules and slimmed server.py from ~970 lines to ~80. NorthAmerica and NewEngland followed suit in their own 0.4.0 releases.

Three-Party Protocol

The Tollbooth ecosystem is a three-party protocol spanning three repositories:

Shortened. The full README is on GitHub.