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

Domain	Tool	Purpose
Strategies	list_strategies	status, strategy_type, title
Strategies	get_strategy	Read one strategy
Strategies	create_strategy	Create a strategy
Strategies	update_strategy	Update selected strategy fields
Overlays	list_overlays	Overlay strategies with their full hedge policy and targets
Overlays	get_overlay_exposure	One overlay's exposure, hedge drift, suggested order, effectiveness and P&L
Overlays	configure_overlay	Set or remove an overlay's role, policy and targets atomically
Backtests	get_backtest_results	List saved backtest runs
Backtests	get_backtest_result	Read one saved backtest run
Orders	list_orders	status, symbol, side, strategy_id
Orders	get_order	Read one CPZ order record
Orders	place_order	Submit an order to the selected connected account
Portfolio	list_positions	account_id, symbol
Portfolio	sync_portfolio	Synchronize connected broker portfolios
Accounts	list_accounts	broker, environment, tradable
Connections	list_connections	connection_type
Connections	create_connection	Store an encrypted provider credential
Data files	list_data_files	name, status, file_type
Data files	get_data_file	Read uploaded file metadata
Market data	get_market_data	Fetch current quotes for symbols
Market data	get_bars	Fetch historical OHLCV bars
Risk	compute_risk	Compute and store a fresh risk snapshot
Risk	list_risk_snapshots	account_id
Risk	get_risk_snapshot	Read one saved risk snapshot
Execution	execute_strategy	Execute strategy code; may place orders
Middle office	list_deals	entity_id, fund, book, deal_id, product_kind, status
Middle office	list_lifecycle_events	entity_id, deal_id, kind, status, from, to
Middle office	list_cash_flows	entity_id, deal_id, fund, book, from, to, unsettled
Middle office	list_journal_entries	entity_id, deal_id, from, to
Middle office	list_fund_periods	entity_id, fund, status
Webhooks	list_webhooks	active
Webhooks	create_webhook	Subscribe an HTTPS endpoint to events
Webhooks	delete_webhook	Remove a webhook subscription
Profile	get_profile	Read your authenticated profile

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

Kind	Name	Purpose
Resource	cpzai://guides/tool-usage	Tool selection, pagination, and capability boundaries
Resource	cpzai://guides/permissions	Resource permissions and execution boundaries
Resource	cpzai://guides/discovery	Endpoints, deferred loading, and the search conventions
Prompt	review_portfolio	Portfolio review workflow; optional account_id
Prompt	analyze_strategy	Strategy investigation; required strategy_id

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:

{
  "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 16 tools instead of 34 (about 18 KB instead of 40 KB, a 56% cut):

• search_tools: natural-language or keyword query, optional category, returns each match with its full input schema. Searches tool names, titles, descriptions, parameter names, and parameter descriptions, so a field name such as unsettled or entity_id finds the tool that accepts it. Categories: strategies, backtests, orders, positions, accounts, market-data, risk, data, webhooks, middle-office, profile.
• call_tool: invokes a discovered tool by name with an arguments object matching its input_schema, and returns that tool's result unchanged.
• Every state-changing tool (place_order, execute_strategy, create_strategy, update_strategy, create_connection, create_webhook, delete_webhook, sync_portfolio, compute_risk, configure_overlay) plus the read anchors list_accounts, list_positions, list_orders, get_market_data.

call_tool dispatches read-only tools only. A client gates approval on the tool name it can see, so routing an order through a generic dispatcher would hide it from the check meant to catch it. It also refuses a read-only tool that is already advertised, and answers an unknown name with near matches rather than a guess. Arguments are validated against the real tool schema before dispatch; a rejection returns the offending paths and that tool's schema.

Protocol revisions

Both endpoints serve the 2026-07-28 revision and every legacy revision back to 2024-10-07 from the same URL.

• A 2026-07-28 client sends each request on its own, with no initialize handshake, names the method in the Mcp-Method header (and the tool in Mcp-Name) so a gateway can route without parsing the body, and carries its protocol version, client info and capabilities in _meta.
• server/discover returns capabilities, instructions and supported versions in one call.
• tools/list, prompts/list, resources/list and server/discover carry ttlMs and cacheScope. tools/list is always private: it is filtered per credential, so a shared cache would hand one key's catalogue to another.
• An initialize-based client negotiates 2025-11-25, 2025-06-18 or older exactly as before. Claude Code and the existing connectors are unaffected.

The server is stateless in both eras: no sessions, no Mcp-Session-Id, one fresh server per request.

Scope-aware discovery

tools/list carries only the tools the calling credential's scopes permit. A data key sees 10 tools, not 34; an identity-only OAuth token sees get_profile alone; search_tools will not return an out-of-scope tool and call_tool will not dispatch one. Scopes come from GET /me on the REST API, cached per credential for 60 seconds and looked up only for tools/list, never on the call path.

If the lookup fails, or the REST API deployment predates the scopes field, the full catalogue is advertised and the reason is logged: unknown is not the same as none. Filtering is discovery, not enforcement. The REST API remains the only thing that decides what a credential may touch, so a tool that is present can still return 403.

Measured surfaces:

Endpoint	Full scopes	data scope only
/mcp	34 tools, ~40 KB	10 tools, ~9 KB
/mcp/compact	16 tools, ~18 KB	6 tools, ~6 KB

Tool names, arguments, results and pagination are identical on both endpoints. Discovery reads no account data and places no order.

Architecture

Remote MCP client
  → POST /mcp  (full catalogue) or POST /mcp/compact (search_tools + call_tool)
  → createMcpHandler, legacy: 'stateless' (2026-07-28 and every legacy revision)
  → fresh stateless server per request
  → user's API credentials, resolved from headers or encrypted OAuth token
  → CPZ REST API /functions/v1/rest-api/v1 (overlay tools: cpz gateway /cpz)
  → existing user-scoped platform handlers

src/tools.ts, src/expanded-tools.ts and src/overlay-tools.ts own the public MCP schemas; src/capabilities.ts defines guide resources and workflow prompts; src/tool-registry.ts captures those same schemas as data and src/tool-search.ts turns them into the compact surface, so the advertised and dispatchable catalogues cannot drift apart. They are distinct from internal Simons tools and are not imported from a shared schema package. The server proxies to the existing REST adapter rather than querying user data with a service-role key. The hosted service also supports authenticated Simons chat proxy routes; those routes are not additional MCP tools.

Local development

npm ci
export CPZ_API_BASE_URL=https://api.cpz-lab.com/functions/v1/rest-api
export MCP_BASE_URL=http://localhost:3001
export MCP_TOKEN_SECRET=replace-with-a-strong-development-secret
npm run dev

The client appends /v1 to CPZ_API_BASE_URL. Its built-in default already includes /functions/v1/rest-api; setting the environment variable to the bare API domain is incorrect. No CPZ_SERVICE_KEY is required by this server.

Variable	Purpose
PORT	HTTP port (default 3001)
CPZ_API_BASE_URL	REST adapter base before /v1
CPZ_API_TIMEOUT_MS	Upstream request timeout budget (default 20000 ms)
CPZ_GATEWAY_BASE_URL	cpz gateway base for the overlay tools (default https://api-ai.cpz-lab.com/cpz)
MCP_BASE_URL	Public origin used in OAuth discovery and redirects
MCP_TOKEN_SECRET	Shared secret for encrypted OAuth tokens and registrations
ALLOW_LEGACY_BEARER	Enables legacy plaintext bearer format only when true
SIMONS_UPSTREAM_URL	Optional Simons proxy upstream override
SENTRY_DSN	Optional error reporting

OAuth registrations, codes, and tokens contain encrypted state. Production replicas must share MCP_TOKEN_SECRET. Without it, development uses a per-process random key and tokens cannot survive restarts or resolve on another replica. Refresh tokens have a 30-day lifetime; previous refresh tokens are not invalidated by rotation. Revoke the underlying CPZ API key to remove access.

Verify and build

npm run export:catalog  # refresh tool-catalog.json after schema/description changes
npm test
npm run build
npm start

Tests cover registration, validation, routing, credentials, response errors, and OAuth behavior. No live order or strategy execution is required for local verification.

Docker

docker build -t cpzai-mcp-server .
docker run --rm -p 3001:3001 \
  -e MCP_BASE_URL=http://localhost:3001 \
  -e MCP_TOKEN_SECRET=replace-with-a-strong-development-secret \
  cpzai-mcp-server

Scope and contributing

The hosted endpoint is the supported user connection. This repository is provided for transparency and local development; production self-hosting is not currently supported. The hosted infrastructure is maintained separately.

CI compares tool-catalog.json with MCP discovery and checks every tool appears in this README. Export the same snapshot to the platform with npm run export:catalog -- --output /path/to/cpzai/src/lib/mcp-tool-catalog.json; its docs test checks the public tool table.

Keep the public schemas, behavioral tests, README, and CPZAI's agent integration docs in sync. Do not advertise internal Simons tools or planned SDK lookup, sandbox, patch, cancellation, or middle-office write capabilities until they have implemented and tested public routes.

MIT © CPZ Capital Ltd.