@fools-gg/mcp

Model Context Protocol server for Fools. Lets an AI agent read live tradeable Metrics, call them up or down, contribute to launch pools, and propose new Metrics, all over the Fools HTTP API.

Defaults to paper mode (no real money, free). Live USDC trading via PincerPay requires explicit opt-in.

Full agent guide: https://fools.com/docs/agents

Install

The server runs client-side, alongside your MCP-compatible client. Nothing is hosted by Fools.

Claude Code

claude mcp add fools -- npx -y @fools-gg/mcp

Claude Desktop / Cursor / Windsurf

Add to your MCP config (paper mode):

{
  "mcpServers": {
    "fools": {
      "command": "npx",
      "args": ["-y", "@fools-gg/mcp"]
    }
  }
}

Live mode (real USDC):

{
  "mcpServers": {
    "fools": {
      "command": "npx",
      "args": ["-y", "@fools-gg/mcp"],
      "env": {
        "FOOLS_MCP_MODE": "live",
        "AGENT_SOLANA_KEY": "<base58 private key>",
        "FOOLS_MCP_SPEND_CAP_USD": "5",
        "FOOLS_MCP_TOOL_CAP_USD": "2"
      }
    }
  }
}

Live mode also requires @pincerpay/agent to be installable (it is an optional peer dependency, lazily imported).

Environment

| Variable | Default | Purpose | |---|---|---| | FOOLS_MCP_MODE | paper | paper or live. | | AGENT_SOLANA_KEY | unset | Base58 Solana keypair (live mode). | | AGENT_EVM_KEY | unset | 0x-prefixed EVM private key (live mode). | | FOOLS_BASE_URL | https://fools.com | Override for staging or local. | | FOOLS_MCP_AGENT_ID | random | Identifies your paper book between sessions. | | FOOLS_MCP_SPEND_CAP_USD | 5 | Session-wide USDC cap. | | FOOLS_MCP_TOOL_CAP_USD | 2 | Per-tool USDC cap. | | FOOLS_MCP_TIMEOUT_MS | 30000 | Per-request timeout. |

Tools

Reads (live, paid per D-103):

• list_metrics, get_metric, get_mark, get_ticks ($0.001 / $0.001 / $0.0001 / $0.0001)
• list_open_calls, list_my_calls, get_my_backed, launch_pool_configs, launch_pool_state ($0.001 each)

Writes (live, paid):

• open_call, close_call ($0.05)
• contribute_launch_pool ($0.25 + your contribution) — requires confirm: true
• propose_metric ($10.00) — requires confirm: true

Free paper variants (paper_open_call, paper_close_call, paper_list_calls) work without PincerPay.

Meta tools (free, client-side): estimate_cost, whoami.

Safety

• Paper-mode default. Live writes only fire when FOOLS_MCP_MODE=live and an AGENT_*_KEY is set.
• Spend caps. The server tracks session and per-tool USDC spent and refuses calls that would exceed the configured cap.
• Confirm gate. propose_metric and contribute_launch_pool reject if the input does not include confirm: true.
• Auto idempotency. Every write attaches an Idempotency-Key header so retries do not double-charge.
• Structured errors. API failures surface as SdkError with code and requestId for branchable handling.

Programmatic use

import { createFoolsMcpServer } from "@fools-gg/mcp/server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = createFoolsMcpServer({ mode: "paper" });
await server.connect(new StdioServerTransport());

For testing, inject a mock FoolsClient:

const server = createFoolsMcpServer({
  mode: "paper",
  foolsClient: mockFoolsClient,
});