Fewsats

Exposes payment operations as standardized MCP (Model Context Protocol) tools that AI agents like Claude can discover and invoke through a FastMCP server framework. The server implements a request-response pattern where agents call tools with structured parameters, the FastMCP framework routes them to handler functions, and responses are serialized back to the agent. This enables AI agents to treat payment operations as first-class capabilities without custom integration code.

Implements a balance() tool that queries the Fewsats payment platform via the Fewsats client library to fetch current wallet balance and account information. The tool makes an authenticated API call using the FEWSATS_API_KEY, receives structured balance data from the backend, and returns it to the agent. This enables agents to check available funds before initiating payments or to report account status.

Exposes a payment_methods() tool that queries the Fewsats platform to retrieve all available payment methods supported by the user's account. The tool calls the Fewsats client library to fetch the list of payment methods, which may include credit cards, bank transfers, cryptocurrency, or other payment rails. Agents can use this to understand what payment options are available before initiating a transaction.

Implements a pay_offer() tool that processes payments by accepting an offer_id and optional l402_offer parameter, then calling the Fewsats client library to execute the payment. The tool supports the L402 protocol (Lightning-402 HTTP authentication), which allows agents to handle payment challenges and proofs in a standardized way. The tool returns payment status and transaction details after execution.

Exposes a payment_info() tool that retrieves detailed information about a specific payment transaction using a payment ID (pid). The tool queries the Fewsats backend via the client library to fetch transaction status, amount, timestamp, payment method used, and other metadata. Agents can use this to verify payment completion, track transaction history, or handle payment failures.

Implements a billing_info() tool that queries the Fewsats platform to retrieve billing-related account information such as billing address, payment history summary, account status, and subscription details. The tool calls the Fewsats client library to fetch this metadata and returns it as structured JSON. Agents can use this to understand account configuration, verify billing status, or generate billing reports.

Manages authentication to the Fewsats payment platform through environment variable-based API key injection. The server reads FEWSATS_API_KEY from the environment at startup and passes it to the Fewsats client library, which uses it to authenticate all API requests. This approach keeps credentials out of code and tool parameters, reducing the risk of accidental exposure. The authentication is transparent to agents — they invoke tools without handling credentials directly.

Builds on the FastMCP framework to automatically register payment tools with standardized schemas, enabling AI agents to discover tool signatures and invoke them through the MCP protocol. The server creates a FastMCP instance, decorates tool functions with MCP metadata, and exposes them through a standardized interface. FastMCP handles protocol negotiation, schema validation, and request routing automatically, abstracting away MCP protocol complexity from tool implementations.

Wraps the Fewsats client library (version 0.0.19+) to provide a consistent interface for all payment operations. The server instantiates the Fewsats client with the API key and delegates all payment API calls to it, handling authentication, request formatting, and response parsing transparently. This abstraction allows the MCP server to focus on tool exposure while the Fewsats client handles protocol details, error handling, and API versioning.