cpzai-mcp-server

A production-grade Model Context Protocol (MCP) server that exposes CPZAI capabilities — strategy management, backtesting, multi-broker order routing (Alpaca / Interactive Brokers / FIX), portfolios, risk analytics, market data — as tools for any MCP-compatible AI agent (Claude, Cursor, GPT, etc.).

The hosted endpoint at https://mcp.cpz-lab.com/mcp is the only supported way to connect. This repo exists for transparency: anyone wiring their broker API keys through an AI agent should be able to read the exact code that handles those keys.

Quick Start

You'll need a CPZ API key + secret. Create one at ai.cpz-lab.com/settings/api-keys.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "cpzai": {
      "url": "https://mcp.cpz-lab.com/mcp",
      "headers": {
        "X-CPZ-Key": "your_cpz_key",
        "X-CPZ-Secret": "your_cpz_secret"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cpzai": {
      "url": "https://mcp.cpz-lab.com/mcp",
      "headers": {
        "X-CPZ-Key": "your_cpz_key",
        "X-CPZ-Secret": "your_cpz_secret"
      }
    }
  }
}

Claude (web / mobile) via OAuth

The server speaks OAuth 2.1 + PKCE at https://mcp.cpz-lab.com/.well-known/oauth-authorization-server. Use Claude's "Connect a server" flow and point it at https://mcp.cpz-lab.com/mcp.

Related MCP server: BotSpot

Architecture

Agent (Cursor / Claude / GPT / custom)
        │
        │  Streamable HTTP + X-CPZ-Key / X-CPZ-Secret
        ▼
   mcp.cpz-lab.com
        │
        ▼
   Node.js MCP server (stateless)  ← this repo
        │
        │  per-request API key validation
        ▼
   CPZ Platform REST API

Design decisions:

• Stateless transport. Each POST /mcp creates a fresh server instance — no session tracking, scales horizontally without coordination.

• Thin protocol adapter. Validates the API key, then proxies tool calls to the CPZ REST API. Zero business logic in the MCP layer; what you see in src/ is what runs in production.

• Key auth. Agents authenticate with CPZ platform API keys (X-CPZ-Key / X-CPZ-Secret) — the same keys used by the REST API and the cpz Python SDK.

• Paper-only by default. Live trading on a strategy requires explicit per-strategy promotion in the platform.

Available tools

18 tools exposed today, organized by domain.

Local development

npm install

export CPZ_API_BASE_URL=https://api.cpz-lab.com
export CPZ_SERVICE_KEY=your_service_key

npm run dev
# server starts on http://localhost:3001

Tests + type check

npm test            # single run
npm run test:watch  # watch mode
npx tsc --noEmit    # type check

Build

npm run build       # compiles TS → dist/
npm start           # runs the compiled server

Docker

docker build -t cpzai-mcp-server .
docker run --rm -p 3001:3001 \
  -e CPZ_API_BASE_URL=https://api.cpz-lab.com \
  -e CPZ_SERVICE_KEY=your_service_key \
  cpzai-mcp-server

Security model

• All connections HTTPS with TLS 1.3 at the edge.

• API credentials are forwarded in HTTP headers and never logged.

• Per-request API key validation against the platform's api_keys table.

• All data access is user-scoped via the user_id derived from the validated key.

• OAuth tokens (when used) are held in server memory only — never persisted.

See the privacy policy for the full data-handling story.

Self-hosting

We don't currently support self-hosting. Use the hosted endpoint at https://mcp.cpz-lab.com/mcp with your CPZ API key. The hosted server is the same code in this repo plus AWS infrastructure (ALB, ECS Fargate, WAF, secrets) that's not part of this repo.

If you have a strong reason to self-host (e.g. air-gapped trading desk), open an issue and we'll talk.

Contributing

Issues and PRs welcome. Before submitting:

• npx tsc --noEmit must pass

• npm test must pass

• Keep changes minimal and aligned with existing patterns

License

MIT © CPZ Capital Ltd.