CPZAI MCP Server

A Model Context Protocol adapter for CPZAI: strategies, saved backtests, broker accounts, orders, portfolio positions, market data, risk, provider connections, and middle-office reporting.

Hosted endpoint: https://mcp.cpz-lab.com/mcp Transport: stateless Streamable HTTP Current source: version 1.2.0 — 31 tools, two guide resources, two workflow prompts.

This README describes the updated source, not a completed production deployment. Use your connected client's tools/list, resources/list, and prompts/list to verify deployed capabilities. The previous source registered 21 tools; old references to 18 tools or a proposed 29-tool release were inaccurate.

Connect

Create a key and secret in Settings → API Keys at CPZAI. In a client supporting remote MCP with custom headers, configure:

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

Use your client's equivalent connector settings when its configuration format differs. OAuth-capable clients can connect to the same MCP URL and complete sign-in using PKCE S256. Discovery endpoints:

• https://mcp.cpz-lab.com/.well-known/oauth-authorization-server
• https://mcp.cpz-lab.com/.well-known/oauth-protected-resource

OAuth access tokens are opaque and accepted by this server. Do not pass them directly to the REST API. Legacy Bearer cpz_key_…SECRET credentials are disabled by default; use header authentication or OAuth.

Tool catalog

Filters in the table are optional. Single-record tools require a CPZ record UUID returned by a corresponding list tool. get_order takes the CPZ record ID, not the broker order ID. File reads return metadata; they do not download file contents or sample rows. Backtest tools read saved runs; they do not start a backtest.

Pagination and data

All list tools take limit (integer 1–100) and offset (nonnegative integer, default 0), plus any sorting fields in their advertised schemas. The default limit is 50, except list_accounts, which defaults to 100. Use an explicit limit when paging. REST count is the current page length, not a total. Continue paging until fewer than limit items are returned before reporting a complete portfolio.

{"limit":100,"offset":0}

For the next page of the same list, use {"limit":100,"offset":100}. An upstream error is not an empty final page.

get_bars accepts symbols, timeframe, start, end, limit (1–10,000 bars per symbol), and feed (iex or sip, subject to provider entitlements). Supported timeframes are 1Min, 5Min, 15Min, 30Min, 1Hour, 2Hour, 4Hour, 1Day, 1Week, and 1Month.

Middle-office lists support optional entity_id for an entity book where the caller is an active member; otherwise they use the personal book. Preserve minor-unit decimal strings as exact values rather than converting them to JavaScript numbers.

Trading and side effects

Use list_accounts to inspect environment and tradable before selecting an account. tradable: true filters to routable accounts; false or omitted includes all. Account discovery covers more providers than order routing. Live or paper execution follows the chosen account and platform controls.

place_order requires positive quantities. Limit/stop-limit orders require price; stop/stop-limit orders require stop_price. Only time_in_force: "day" is exposed, because legacy routes support that duration only. Supported order types remain broker-dependent. execute_strategy can place trades and is not a signal preview or dry run. Invoke these tools only for trading the user has authorized.

Tool annotations describe side effects. Actual authorization is enforced by the REST API's key, subscription, ownership, and resource-scope checks. Legacy read/write/trade permissions are expanded by that API into resource scopes.

Results and errors

Tool responses preserve readable JSON text and include structured content. Most read tools declare an outputSchema so a client can validate what came back: list routes return {data, count}, single-record routes return {data}, and a delete returns {message}. The action tools that proxy to another service (execute_strategy, sync_portfolio, compute_risk, get_market_data, get_bars) and the two writes with their own handlers (place_order, create_connection) declare no output schema, because their shape is not this server's to promise. Output validation is skipped for error results. Check isError before using the result. Malformed upstream responses and provider failures stay errors. Request IDs support tracing without logging credentials.

Eligible GET calls can retry transient upstream failures within a bounded timeout. Writes are not automatically retried. A timeout after order submission leaves the result unconfirmed; inspect existing orders and the broker before retrying. The public order route does not provide a general end-to-end idempotency guarantee.

Resources and prompts

Requesting a prompt returns instructions; it does not execute a workflow. Discover these using standard MCP methods. There is no /mcp/info endpoint.

Progressive tool discovery

The full catalogue is 31 tools and roughly 27 KB of JSON Schema, which every client pays for on every request unless it can defer tool loading. Tool-selection accuracy also falls off once a model is choosing between more than about thirty tools. There are two endpoints, serving identical tools under different discovery models.

POST /mcp: full catalogue

tools/list returns every tool. Use this when the client defers loading itself: it needs the definitions in order to defer them. With Claude's MCP connector, pair defer_loading with the tool search tool and keep the everyday reads loaded:

{
  "type": "mcp_toolset",
  "mcp_server_name": "cpzai",
  "default_config": { "defer_loading": true },
  "configs": {
    "list_accounts":  { "defer_loading": false },
    "list_positions": { "defer_loading": false },
    "place_order":    { "defer_loading": false }
  }
}

Deferred definitions are still sent on every request; they stay out of the model's context until a search discovers them, and the prompt prefix is untouched, so the cache survives. Claude Code applies its own tool search to this endpoint with no configuration.

POST /mcp/compact: server-side discovery

For clients with no deferral of their own. tools/list returns 15 tools instead of 31 (about 12 KB instead of 27 KB, a 55% cut):