{ "markdown": "

CPZAI MCP Server

\n\n

\n Model Context Protocol server for AI agent access to CPZAI\n

\n\n

\n \"TypeScript\"\n \"CI\"\n \"MCP\n \"Streamable\n \"License:\n

\n\n---\n\nA production-grade [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes [CPZAI](https://ai.cpz-lab.com) 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.).\n\nThe 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.\n\n## Quick Start\n\nYou'll need a CPZ API key + secret. Create one at [ai.cpz-lab.com/settings/api-keys](https://ai.cpz-lab.com/settings/api-keys).\n\n### Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"cpzai\": {\n \"url\": \"https://mcp.cpz-lab.com/mcp\",\n \"headers\": {\n \"X-CPZ-Key\": \"your_cpz_key\",\n \"X-CPZ-Secret\": \"your_cpz_secret\"\n }\n }\n }\n}\n```\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"cpzai\": {\n \"url\": \"https://mcp.cpz-lab.com/mcp\",\n \"headers\": {\n \"X-CPZ-Key\": \"your_cpz_key\",\n \"X-CPZ-Secret\": \"your_cpz_secret\"\n }\n }\n }\n}\n```\n\n### Claude (web / mobile) via OAuth\n\nThe 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`.\n\n## Architecture\n\n```\nAgent (Cursor / Claude / GPT / custom)\n │\n │ Streamable HTTP + X-CPZ-Key / X-CPZ-Secret\n ▼\n mcp.cpz-lab.com\n │\n ▼\n Node.js MCP server (stateless) ← this repo\n │\n │ per-request API key validation\n ▼\n CPZ Platform REST API\n```\n\n**Design decisions:**\n\n- **Stateless transport.** Each `POST /mcp` creates a fresh server instance — no session tracking, scales horizontally without coordination.\n- **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.\n- **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](https://pypi.org/project/cpz/).\n- **Paper-only by default.** Live trading on a strategy requires explicit per-strategy promotion in the platform.\n\n## Available tools\n\n18 tools exposed today, organized by domain.\n\n| Tool | Description | Read-only |\n|------|-------------|:---------:|\n| **Strategies** | | |\n| `list_strategies` | List trading strategies with filtering | ✓ |\n| `get_strategy` | Get a specific strategy by ID | ✓ |\n| `create_strategy` | Create a new trading strategy | |\n| `update_strategy` | Update an existing strategy | |\n| **Backtests** | | |\n| `get_backtest_results` | List backtest run results | ✓ |\n| **Orders & trading** | | |\n| `list_orders` | List trading orders with filtering | ✓ |\n| `place_order` | Place a new trading order | |\n| `list_positions` | List current portfolio positions | ✓ |\n| `sync_portfolio` | Trigger portfolio sync across brokers | |\n| `list_accounts` | List connected trading accounts | ✓ |\n| **Market data** | | |\n| `get_market_data` | Real-time quotes (price, bid/ask, volume) | ✓ |\n| **Risk** | | |\n| `compute_risk` | Compute fresh risk snapshot (VaR, Sharpe, drawdown) | |\n| `list_risk_snapshots` | List historical risk snapshots | ✓ |\n| **Execution** | | |\n| `execute_strategy` | Execute a strategy on the Python backend | |\n| **Webhooks** | | |\n| `list_webhooks` | List webhook subscriptions | ✓ |\n| `create_webhook` | Subscribe to platform events | |\n| `delete_webhook` | Remove a webhook subscription | |\n| **User** | | |\n| `get_profile` | Get authenticated user profile | ✓ |\n\n## Local development\n\n```bash\nnpm install\n\nexport CPZ_API_BASE_URL=https://api.cpz-lab.com\nexport CPZ_SERVICE_KEY=your_service_key\n\nnpm run dev\n# server starts on http://localhost:3001\n```\n\n### Tests + type check\n\n```bash\nnpm test # single run\nnpm run test:watch # watch mode\nnpx tsc --noEmit # type check\n```\n\n### Build\n\n```bash\nnpm run build # compiles TS → dist/\nnpm start # runs the compiled server\n```\n\n### Docker\n\n```bash\ndocker build -t cpzai-mcp-server .\ndocker run --rm -p 3001:3001 \\\n -e CPZ_API_BASE_URL=https://api.cpz-lab.com \\\n -e CPZ_SERVICE_KEY=your_service_key \\\n cpzai-mcp-server\n```\n\n## Security model\n\n- All connections HTTPS with TLS 1.3 at the edge.\n- API credentials are forwarded in HTTP headers and **never logged**.\n- Per-request API key validation against the platform's `api_keys` table.\n- All data access is user-scoped via the `user_id` derived from the validated key.\n- OAuth tokens (when used) are held in server memory only — never persisted.\n\nSee the [privacy policy](https://mcp.cpz-lab.com/privacy) for the full data-handling story.\n\n## Self-hosting\n\nWe 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.\n\nIf you have a strong reason to self-host (e.g. air-gapped trading desk), open an issue and we'll talk.\n\n## Contributing\n\nIssues and PRs welcome. Before submitting:\n\n- `npx tsc --noEmit` must pass\n- `npm test` must pass\n- Keep changes minimal and aligned with existing patterns\n\n## License\n\n[MIT](LICENSE) © CPZ Capital Ltd.\n", "bytes": 6463, "sha": "aa10c1de25cd1ff782405d253a4bf83e6ffa1a7fef7b42bbe30547b3811aeb64", "repo_slug": "cpz-lab/cpzai-mcp-server", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_com_cpz_lab_mcp_cpzai_cbed87d7/readme" }