# Tollbooth Sample

> Tollbooth Sample is an open-source MCP server for developer tools. Sample MCP server returning weather data, showing Lightning-paid tool calls for developers. It runs as a hosted remote server, so there is nothing to install locally.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** API, self-hosted
- **Repository:** https://github.com/lonniev/tollbooth-sample
- **MCP Registry name:** io.github.lonniev/tollbooth-sample
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
claude mcp add --transport http tollbooth-sample https://tollbooth-sample.fastmcp.app/mcp
```

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://tollbooth-sample.fastmcp.app/mcp
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "tollbooth-sample": {
      "url": "https://tollbooth-sample.fastmcp.app/mcp"
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "tollbooth-sample": {
      "type": "http",
      "url": "https://tollbooth-sample.fastmcp.app/mcp"
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "tollbooth-sample": {
      "serverUrl": "https://tollbooth-sample.fastmcp.app/mcp"
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "tollbooth-sample": {
      "type": "http",
      "url": "https://tollbooth-sample.fastmcp.app/mcp"
    }
  }
}
```

## Tools

- `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

## 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.

## Alternatives

- [x402 Tool Shop](https://ai-powered.com/mcp/x402-tool-shop): x402 Tool Shop is a paid MCP server for developer tools.
- [Weather](https://ai-powered.com/mcp/weather-7): Weather is an open-source MCP server for maps and travel.
- [Toolweather](https://ai-powered.com/mcp/toolweather): Toolweather is a freemium MCP server for developer tools.
- [Tollkit](https://ai-powered.com/mcp/tollkit): Tollkit is a paid MCP server for finance and payments.
- [Agent Evidence Utility](https://ai-powered.com/mcp/agent-evidence-utility): Agent Evidence Utility is a paid MCP server for files and documents.
- [Agent Tollbooth 402](https://ai-powered.com/mcp/agent-tollbooth-402): Agent Tollbooth 402 is a freemium MCP server for developer tools.
- [Smarter Weather Developer Onboarding](https://ai-powered.com/mcp/smarter-weather-developer-onboarding): Smarter Weather Developer Onboarding is a freemium MCP server for maps and travel.
- [Diogenes Autonomous Microservice Gateway](https://ai-powered.com/mcp/diogenes-autonomous-microservice-gateway): Diogenes Autonomous Microservice Gateway is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/tollbooth-sample
