Running the FutureSearch MCP Server Locally

Two-container stack: mcp-server (FastAPI on :8000) and redis (on :6379), orchestrated by futuresearch-mcp/deploy/docker-compose.yaml with local overrides.

Pre-flight Checks

CRITICAL: Always check for stale processes on port 8000 before starting.

A leftover futuresearch-mcp --no-auth or similar process on the host will shadow the Docker container's port binding. All requests hit the stale process instead of the container — this can look like auth routes are broken, sheets tools are missing, etc.

# Check for anything on port 8000
lsof -i :8000

# Kill if needed
lsof -ti :8000 | xargs kill -9

Also check Docker is running:

docker info --format '{{.ServerVersion}}' || colima start

Quick Start

cd futuresearch-mcp/deploy

REDIS_PASSWORD=testpass \
MCP_SERVER_URL=http://localhost:8000 \
  docker compose \
    -f docker-compose.yaml \
    -f docker-compose.local.yaml \
  up -d --build

Verify: curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/health should return 200.

Optional env vars

Pass these alongside REDIS_PASSWORD and MCP_SERVER_URL:

These are templated in docker-compose.local.yaml as ${VAR:-default} — the container must be recreated (not just restarted) for env var changes to take effect.

Secrets

The .env file at futuresearch-mcp/deploy/.env contains production secrets (Supabase, API keys, upload secret). It is already present and should NOT be committed or overwritten.

REDIS_PASSWORD is intentionally NOT in .env — always pass it as an env var (testpass for local dev).

Worktrees

The .env file is gitignored and won't exist in worktrees. Symlink it:

ln -s /Users/rafaelpoyiadzi/Documents/git/futuresearch-python/futuresearch-mcp/deploy/.env \
      <worktree-path>/futuresearch-mcp/deploy/.env

Exposing via Cloudflare Tunnel

Required when testing with Claude.ai or Claude Desktop, which can't reach localhost.

Step 1: Kill stale tunnels and processes

pkill -f cloudflared 2>/dev/null
rm -f /tmp/cf-tunnel.log
lsof -ti :8000 | xargs kill -9 2>/dev/null

Step 2: Start the tunnel

cloudflared tunnel --url http://localhost:8000 2>/tmp/cf-tunnel.log &
sleep 6
grep -oE 'https://[a-z0-9-]+\.trycloudflare\.com' /tmp/cf-tunnel.log | head -1

This prints a URL like https://something-something.trycloudflare.com.

Step 3: Start (or restart) the MCP server with the tunnel URL

The server must know its public URL for OAuth redirects to work:

cd futuresearch-mcp/deploy

REDIS_PASSWORD=testpass \
MCP_SERVER_URL=https://something-something.trycloudflare.com \
TRUST_PROXY_HEADERS=true \
ENABLE_SHEETS_TOOLS=true \
  docker compose \
    -f docker-compose.yaml \
    -f docker-compose.local.yaml \
  up -d --build

Key: MCP_SERVER_URL must match the tunnel URL exactly, and TRUST_PROXY_HEADERS=true is required so the server trusts the forwarded headers from Cloudflare.

Step 4: Verify OAuth discovery works end-to-end

# Through the tunnel (what Claude.ai sees)
curl -s https://<tunnel-url>/.well-known/oauth-authorization-server | python3 -m json.tool | head -5

# Locally
curl -s http://localhost:8000/.well-known/oauth-authorization-server | python3 -m json.tool | head -5

Both should return JSON with issuer, authorization_endpoint, etc. If local returns 404 but tunnel works (or vice versa), check for stale processes on port 8000.

Step 5: Connect clients

Claude.ai / Claude Desktop: Use the tunnel URL as the MCP server URL in the client config.

Claude Code: Add a project-scoped MCP server (writes to .claude/settings.local.json in the current dir, not the global config):

claude mcp add futuresearch --scope project --transport http <TUNNEL_URL>/mcp

Then restart Claude Code. Remove with claude mcp remove futuresearch --scope project.

Logs

# All logs
docker logs deploy-mcp-server-1 -f

# Filter for errors
docker logs deploy-mcp-server-1 2>&1 | grep -iE "error|warn|401|500"

# Check User-Agent strings (for widget/client detection work)
docker logs deploy-mcp-server-1 2>&1 | grep "User-Agent"

Teardown

cd futuresearch-mcp/deploy

REDIS_PASSWORD=testpass MCP_SERVER_URL=http://localhost:8000 \
  docker compose -f docker-compose.yaml -f docker-compose.local.yaml down

Kill the tunnel: pkill -f cloudflared or kill %1 if it was backgrounded.

No-Auth Mode (without Docker)

Run the server directly with uv run — no Docker needed. Useful for quick local testing with the MCP Inspector.

WARNING: If you leave this running and later start the Docker stack, the local process will shadow Docker's port 8000. Always kill it first: lsof -ti :8000 | xargs kill -9

Prerequisites

• Redis running on localhost:6379 (e.g. docker run -d --name test-redis -p 6379:6379 redis:7-alpine)
• FUTURESEARCH_API_KEY (or legacy FUTURESEARCH_API_KEY) in ~/.claude/secrets/remote.env

Start the server

cd futuresearch-mcp
ALLOW_NO_AUTH=1 \
UPLOAD_SECRET=$(python -c "import secrets; print(secrets.token_urlsafe(32))") \
EXTRA_ALLOWED_HOSTS="host.docker.internal,localhost" \
  bash scripts/run-no-auth.sh

Connect with MCP Inspector

1. Start the Inspector: npx @modelcontextprotocol/inspector
2. Open the URL it prints (includes MCP_PROXY_AUTH_TOKEN)
3. Settings:

• Transport: Streamable HTTP
• Mode: Via Proxy
• URL: http://localhost:8000/mcp
• Leave all OAuth fields blank

1. Click Connect

Note: Direct mode won't work (CORS). Auth mode won't work (Inspector v0.21.0 doesn't handle the OAuth flow). Use Via Proxy with no-auth.

Connect with SDK client

uv run python scripts/mcp_call.py list
uv run python scripts/mcp_call.py call futuresearch_balance
uv run python scripts/mcp_call.py call futuresearch_agent '{"params": {"task": "...", "data": [...]}}'

Note: mcp_call.py only works against --no-auth servers. It doesn't do OAuth, so authenticated servers will show a subset of tools or fail.

Common Issues

Key Files