Skip to content
MCP server

Tollbooth Sample

Sample MCP server returning weather data, showing Lightning-paid tool calls for developers

Install
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/mcp

Add to Settings → Connectors → Add custom connector

https://tollbooth-sample.fastmcp.app/mcp
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "tollbooth-sample": {
      "url": "https://tollbooth-sample.fastmcp.app/mcp"
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

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.

How AIPoweredBot checks servers