@obolo/mcp-server

@obolo/mcp-server

MCP server that exposes Obolo marketplace APIs as payable tools for any MCP-compatible AI client (Claude Desktop, Cursor, Windsurf, etc.).

Each Obolo marketplace endpoint becomes an MCP tool that agents can discover, price-check, and invoke with automatic stablecoin payment.

Installation

npm install -g @obolo/mcp-server

Or run directly with npx:

npx @obolo/mcp-server

Configuration

The server pays on one chain per instance — you pick the chain with OBOLO_CHAIN and provide the matching key. Only that chain's key env is read, so a single instance never holds more than one spending credential.

Environment Variable	Required	Default	Description
OBOLO_CHAIN	No	8453 (Base)	Chain to pay on: an EVM chain id (8453, 1, 42161, 10, 137, 56, 43114) or solana-mainnet / aptos-mainnet / stellar-mainnet / ton-mainnet
OBOLO_MAX_PRICE_USDC	No	0.10	Per-call price cap (USD). A call whose 402 price exceeds this is refused before any funds move
OBOLO_BUDGET_USDC	No	—	Optional cumulative session cap. Fail-closed: a call is refused if it could push total spend past this
GATEFLOW_CATALOG_URL	No	https://www.obolo.io/api/marketplace/catalog	Obolo catalog endpoint
GATEFLOW_PROXY_URL	No	https://proxy.obolo.io	Obolo proxy base URL

Chain key (set exactly the one for your OBOLO_CHAIN):

Chain	Key env	Format	Also install
EVM (8453, 1, …)	OBOLO_WALLET_KEY	0x… private key	viem
Solana	OBOLO_SOLANA_SECRET_KEY	base58 secret, or JSON array […]	@solana/web3.js @solana/spl-token tweetnacl
Aptos	OBOLO_APTOS_PRIVATE_KEY	0x… ed25519 key	@aptos-labs/ts-sdk
Stellar	OBOLO_STELLAR_SECRET	S… seed	@stellar/stellar-sdk
TON	OBOLO_TON_MNEMONIC	space-separated words	@ton/ton @ton/crypto

For TON you can also set OBOLO_TON_ENDPOINT (a dedicated RPC URL, e.g. Orbs ton-access) and/or OBOLO_TONCENTER_API_KEY to lift the public toncenter rate limit. Neither is required — without them the rail uses the public endpoint and auto-retries through its 429s (slower, not broken).

Without a matching key, the server runs in discovery-only mode: agents can list tools but not execute them. (An EVM chain not in the built-in list needs OBOLO_EVM_RPC_URL. TON is supported end-to-end — the proxy's TON verifier is live and has settled a real mainnet USD₮ payment.)

Security. Payment is fail-closed and prompt-injection-resistant: the recipient, amount, and token come from the proxy's signed 402 — never from the LLM or a tool argument — so a compromised or manipulated client cannot redirect funds or overspend past OBOLO_MAX_PRICE_USDC. Keep the budget caps set.

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "gateflow": {
      "command": "npx",
      "args": ["@obolo/mcp-server"],
      "env": {
        "OBOLO_CHAIN": "8453",
        "OBOLO_WALLET_KEY": "0x...",
        "OBOLO_MAX_PRICE_USDC": "0.10"
      }
    }
  }
}

Cursor / Windsurf

Add to your MCP configuration:

{
  "mcpServers": {
    "gateflow": {
      "command": "npx",
      "args": ["@obolo/mcp-server"],
      "env": {
        "OBOLO_CHAIN": "8453",
        "OBOLO_WALLET_KEY": "0x...",
        "OBOLO_MAX_PRICE_USDC": "0.10"
      }
    }
  }
}

How It Works

1. On startup, the server fetches the Obolo marketplace catalog
2. Each endpoint is registered as an MCP tool with its name, description, and price
3. When an AI client invokes a tool, the server (via the SDK payment rail for OBOLO_CHAIN):
   • Probes the endpoint's 402, enforces the price cap, sends the stablecoin payment on the selected chain
   • Signs that chain's wallet-proof and forwards the request through the Obolo proxy with the payment hash
   • Auto-retries while the proxy's node catches up to the tx (never double-paying)
   • Returns the API response as the tool result
4. Payment metadata (tx hash, chain, token, amount) + running budget are included in the response _meta

Tool Schema

Each marketplace endpoint becomes a tool with this input schema:

{
  "query": "string (required) - The query or input to send to the API",
  "method": "string (optional) - HTTP method: GET, POST, PUT, DELETE, PATCH",
  "params": "object (optional) - Query parameters as key-value pairs"
}

Development

# Build from source
npm run build

# Run locally
GATEFLOW_WALLET_KEY=0x... node dist/index.js

License

MIT