Overview

The Fewsats MCP Server is a lightweight Model Context Protocol (MCP) server that connects AI agents to Fewsats for secure, verifiable payments. It exposes a small set of tools that let an agent inspect wallet balances, list payment methods, initiate payments for offers, and query payment status. By handling payment context tokens and payment request URLs within a server designed for MCP, it makes machine-driven purchases more predictable and safer.

This server is useful when you want an AI agent to autonomously complete transactions — for example, buy a dataset, purchase compute credits, or pay for a third‑party API — while ensuring the payment flow is auditable and controlled. It integrates easily with agent platforms that support MCP servers (such as Claude Desktop) and can be run locally or in small cloud environments.

Features

Simple MCP-compatible API to integrate payments into AI agent workflows
Support for balance checks and listing saved payment methods
Secure offer payment flow that accepts Fewsats offer objects and tokens
Payment information lookup to confirm and audit transaction outcomes
Run with uvx (recommended) or installable via pip for straightforward deployment

Repository: https://github.com/Fewsats/fewsats-mcp

Installation / Configuration

Recommended: run with uvx (no build/installation required)

# Run directly with uvx (requires uv/uvx installed)
uvx fewsats-mcp

Pip installation (alternative)

pip install fewsats-mcp

# After installing, run as a normal Python console script
fewsats-mcp

Environment variable

FEWSATS_API_KEY: your API key from https://fewsats.com used to authenticate requests.

Example environment run:

export FEWSATS_API_KEY="sk_live_..."
uvx fewsats-mcp

Configuration for Claude Desktop Add an MCP server entry to your claude_desktop_config.json. Replace YOUR_FEWSATS_API_KEY accordingly.

"mcpServers": {
  "Fewsats Server": {
    "command": "uvx",
    "args": ["fewsats-mcp"],
    "env": {
      "FEWSATS_API_KEY": "YOUR_FEWSATS_API_KEY"
    }
  }
}

Available Tools

The server exposes four MCP tools designed for agent use. Each returns JSON-serializable results suitable for programmatic consumption.

balance
- Purpose: Retrieve the current balance for the configured Fewsats wallet.
- Input: none
- Output: current wallet balance details (amount, currency, available credits)
payment_methods
- Purpose: List stored or available payment methods for the user.
- Input: none
- Output: array of payment method objects (id, type, last4, metadata)
pay_offer
- Purpose: Pay an offer described by a Fewsats l402_offer payload.
- Input:
  - offer_id (string): identifier of the selected offer
  - l402_offer (object): the offer object returned by Fewsats, typically containing:
    - offers: array of offer entries {id, amount, currency, title, description}
    - payment_context_token: token to authorize the payment context
    - payment_request_url: URL for completing or verifying the payment
    - version: API version string
- Output: payment initiation result (status, transaction id, error details if any)
payment_info
- Purpose: Fetch detailed information about a specific payment.
- Input:
  - pid (string): the payment id to query
- Output: comprehensive payment record (status, timestamps, amounts, receipt metadata)

Tools table (quick reference)

Tool	Inputs	Returns
balance	none	wallet balance
payment_methods	none	list of payment methods
pay_offer	offer_id, l402_offer	payment status / transaction id
payment_info	pid	detailed payment info

Use Cases

Autonomous Digital Purchases
- An AI agent detects a required dataset behind a paywall, calls balance, selects an offer from a listing, and uses pay_offer to complete the purchase. Afterwards it calls payment_info to store the transaction metadata for auditing.
Microtransactions for Plugins
- A multi-plugin agent needs to top up credits for a paid plugin. It checks payment_methods to pick a stored card, pays the plugin’s offer via pay_offer, and confirms via payment_info.
Subscription Renewal Automation
- An automation agent monitors subscription expirations. When renewal is needed it verifies funds with balance, initiates renewal using pay_offer with the subscription offer, and logs the result for compliance.
Human-in-the-loop Controlled Payments
- When higher-privilege purchases are detected, the agent prepares a payment request (payment_request_url) and surfaces it to a human reviewer. The reviewer completes or approves the URL; the agent then verifies via payment_info.

Security and Operational Notes

Keep FEWSATS_API_KEY secret and scope it to least privilege. Prefer injected environment variables rather than checked-in files.
pay_offer expects validated l402_offer payloads (including payment_context_token) from Fewsats; do not fabricate tokens.
Log payment_info responses for audit trails and dispute resolution, but avoid logging full payment method details (PII or PAN data).

Resources

Source & issues: https://github.com/Fewsats/fewsats-mcp
Fewsats: https://fewsats.com

If you need to integrate this MCP into a different agent framework, treat the server as any MCP-compatible toolset: expose the four endpoints to the agent, provide the FEWSATS_API_KEY, and adapt the agent’s logic to call balance/payment_methods before initiating pay_offer.

Fewsats MCP Server for Secure AI Agent Purchases