Install

Prerequisites

Python 3.10+
An MCP-compatible client (Claude Code, Cursor, Cline, Windsurf, etc)

Package install

pip install falsifylab-alpha-mcp

That’s the whole install. The package has zero runtime dependencies — uses Python stdlib only.

Claude Code

claude mcp add falsifylab-alpha -- python -m falsifylab_alpha_mcp

To add an API key (Pro tier):

claude mcp add falsifylab-alpha \
  --env FL_API_KEY=fl_yourkey \
  -- python -m falsifylab_alpha_mcp

Restart Claude Code. Tools auto-discovered.

Cursor (.mcp.json)

{
  "mcpServers": {
    "falsifylab-alpha": {
      "command": "python",
      "args": ["-m", "falsifylab_alpha_mcp"],
      "env": {
        "FL_API_KEY": "fl_yourkey"
      }
    }
  }
}

Drop into ~/.cursor/mcp.json or project root. Restart Cursor.

Cline

Settings → MCP Servers → Add Server:

Command: python
Args: ["-m", "falsifylab_alpha_mcp"]
Env: FL_API_KEY=fl_yourkey (optional)

Windsurf

Settings → MCP → Add Server. Use same config as Cursor.

Free tier (no API key)

Skip the FL_API_KEY env var. Server auto-issues a tier-0 key on first call. Cached 24h, 10 results per query.

Pro tier

Get a key at falsifylab.com/pro ($19/mo, 7-day trial). Real-time data, 100 results per query, 90 days of history.

Verify install

In your agent, ask: “call the macro_tape tool and show me the BTC/ETH 1d returns”. If the agent returns numbers, you’re live.

Troubleshooting

Symptom	Fix
`command not found: falsifylab-alpha-mcp`	Use `python -m falsifylab_alpha_mcp` instead
`429 rate limited`	Hit free-tier cap. Wait 1hr or upgrade
`connection refused`	FalsifyLab API down — check status.falsifylab.com
Tools missing in agent	Restart agent. Verify `mcp list` shows `falsifylab-alpha`

Open an issue →