Tollbooth Sample
Sample MCP server returning weather data, showing Lightning-paid tool calls for developers
- Pricing
- Open source
- Platforms
- API, self-hosted
- Runs
- Remotely
- Version
- 0.5.0
- Listing updated
- today
Similar MCP servers
About Tollbooth Sample
Tollbooth Sample is an open-source MCP server for developer tools. It runs as a hosted remote server, so there is nothing to install locally.
The README describes this as an educational reference implementation: a weather statistics MCP service that wraps the free Open-Meteo API and gates selected tool calls behind prepaid credits. Current conditions, multi-day forecasts and historical weather are exposed as tools, each priced by a cost category such as read, write or heavy.
Payments use the Tollbooth DPYC framework. Users buy credits over Bitcoin Lightning, are identified by a Nostr public key rather than an account, and are debited automatically per call. The README says failed downstream calls are rolled back so the user is not charged. Standard tools for balance checks, purchases, pricing and onboarding are provided by the SDK.
The repository is aimed at developers who want to see how a monetized MCP operator is structured, and it doubles as a Claude Code plugin for converting an existing API into a paid operator. It is deployed as a streamable-HTTP endpoint, and the README notes that paid tools cannot be exercised over STDIO.
Install
Run in a terminal
claude mcp add --transport http tollbooth-sample https://tollbooth-sample.fastmcp.app/mcpAdd to Settings → Connectors → Add custom connector
https://tollbooth-sample.fastmcp.app/mcpAdd to ~/.cursor/mcp.json
{
"mcpServers": {
"tollbooth-sample": {
"url": "https://tollbooth-sample.fastmcp.app/mcp"
}
}
}Add to .vscode/mcp.json
{
"servers": {
"tollbooth-sample": {
"type": "http",
"url": "https://tollbooth-sample.fastmcp.app/mcp"
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"tollbooth-sample": {
"serverUrl": "https://tollbooth-sample.fastmcp.app/mcp"
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"tollbooth-sample": {
"type": "http",
"url": "https://tollbooth-sample.fastmcp.app/mcp"
}
}
}Using several servers? Build one config file with the MCP config generator.
Tools this server provides (9)
Taken from the project documentation; the running server may differ.
- weather_current
- Current weather for lat/lon
- weather_forecast
- Multi-day forecast (1-16 days)
- weather_historical
- Historical weather for a date range
- weather_check_balance
- Check credit balance
- weather_purchase_credits
- Buy credits via Lightning
- weather_check_payment
- Check invoice status
- weather_request_adoption
- Request adoption by an Authority
- weather_check_price
- Preview cost with constraint effects
- weather_service_status
- Health and constraint config summary
What it does
- Current weather lookup
- Returns temperature, wind speed and weather code for a latitude and longitude.
- Multi-day forecast
- Provides a weather forecast covering one to sixteen days.
- Historical weather data
- Returns past weather for a requested date range.
- Automatic credit debiting
- The paid-tool decorator handles balance checks, debits and rollbacks without custom code in each tool.
- Lightning credit purchases
- Users top up prepaid balances with Bitcoin Lightning invoices.
- Configurable pricing constraints
- Pricing chains can include free trials, discounts, supply caps and surge pricing.
Good for
- Studying how to add prepaid pay-per-call billing to an MCP server
- Building a monetized weather data operator from the reference template
- Querying current conditions or forecasts for a coordinate from an AI client
- Retrieving historical weather for a date range
Pricing
Open source
Open-source Apache-2.0 sample; tool calls are paid in Lightning credits set by the operator's pricing model.
Tollbooth Sample FAQ
Is the weather data source free?
The README says the service wraps the free Open-Meteo weather API.
Can I try paid tools locally over STDIO?
No. The README says paid tools are refused over STDIO, so they must be exercised against a deployed instance.
Are failed calls charged?
The README says credits are rolled back automatically if the downstream API fails after a debit.
How are users identified?
By a Nostr public key (npub) rather than an email or password, according to the README.
Is Tollbooth Sample free?
Yes. Tollbooth Sample is open source, so you can use and self-host it for free.
How do I add Tollbooth Sample to Claude Code?
Run this command in your terminal: claude mcp add --transport http tollbooth-sample https://tollbooth-sample.fastmcp.app/mcp
What are the best alternatives to Tollbooth Sample?
The closest alternatives to Tollbooth Sample are x402 Tool Shop, Weather, Toolweather, Tollkit and Agent Evidence Utility.
Where this comes from
- Description: written from the project's README and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.