CPZAI

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.4.0: 34 tools, three 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.

Overlays

An overlay is a strategy that hedges other strategies or whole broker accounts under a hedge policy. All three overlay tools call the cpz gateway with your own credential and need the strategies scope.

list_overlays (GET /cpz/overlays) returns every overlay with its full policy (objective, hedge ratio, tolerance band, hedge instruments, benchmark, rebalance trigger, notes) and targets, in one read with no market data. configured is true when an overlay has a policy and at least one target. The platform returns at most 200 overlays, ordered by title; truncated: true says more exist, and the result then carries a note that it is not the complete list.

get_overlay_exposure (GET /cpz/overlay/exposure) resolves one overlay's hedge. Its result leads with the verdict: complete, hedge_ratio_status (measured, not_measured for objectives with no ratio or nothing to hedge, or withheld) and hedge_ratio_reason, then the platform document under data. When complete is false a price or price history is missing, and the hedge ratio, drift, band flag and suggested order are null with a withheld block naming the missing symbols. Never size or place a hedge from an incomplete result. The suggested order is advice; placing it is a separate, user-authorized place_order call. A 409 means the strategy is not an overlay or has no policy or targets yet, and points at configure_overlay.

configure_overlay (PUT /cpz/overlays/{id}) saves role, policy and targets in one transaction and returns the saved configuration.

• role: "overlay" needs a policy and at least one target, and replaces both. Policy fields you omit take their defaults (hedge_ratio 1, tolerance_band 0.1, rebalance_trigger band, no instruments, no notes), and targets you do not list are removed. Read list_overlays first and send the whole configuration.
• role: "alpha" removes the policy and targets. Pass neither with it.
• Becoming an overlay turns short selling on for the strategy.
• The tool refuses before any request: an unknown objective, hedge_ratio outside 0 to 5, tolerance_band outside (0, 1], a beta overlay without benchmark_symbol, no targets, a self-target, the same target twice, a weight outside (0, 10], an account environment other than paper or live, and misspelt fields. Ownership, account membership and cycles are checked by the platform, whose 400 message is passed through verbatim.
• A 200 whose read-back failed is reported as saved, with a note to confirm it with list_overlays. A 5xx, a timeout or an unreadable 200 is never reported as a save: the outcome is unknown, so check list_overlays before saving again. The write is never retried.

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 writes with their own handlers (place_order, create_connection, configure_overlay) 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 34 tools and roughly 40 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:

`jso