feat(mcp): overlay tools: list_overlays, get_overlay_exposure, configure_overlay

[chris-cpz]

Summary

Overlay strategies are live on the platform, but an MCP client could not see or configure them. This adds three tools. All three call the cpz gateway (https://api-ai.cpz-lab.com/cpz) with the caller's own X-CPZ-Key / X-CPZ-Secret and need the strategies scope. OAuth tokens are unsealed to that same pair, and the gateway authenticates and scopes it the same way rest-api does. This server already calls the same host for the Simons proxy.

Tool	Platform call	Kind
list_overlays	GET /cpz/overlays	read-only
get_overlay_exposure	GET /cpz/overlay/exposure?strategy_id=<uuid>	read-only
configure_overlay	PUT /cpz/overlays/{uuid}	destructive, idempotent write

The write route came from CPZ-Lab/cpzai#1736 (save_overlay_config_as, merged and deployed). The first commit on this branch shipped the two reads only, with the gap written up; the second adds configure_overlay and moves list_overlays onto the new config route.

list_overlays

• One read, no market data. Each overlay comes back with its full policy (objective, hedge_ratio, tolerance_band, hedge_instruments, benchmark_symbol, rebalance_trigger, notes) and its targets. configured is true when an overlay has a policy and at least one target.
• The result is {data, count, truncated}. The platform returns at most 200 overlays, ordered by title. When truncated is true the result adds a note saying it is not the complete list.
• A 200 with no overlays array or no boolean truncated is refused as invalid_upstream_response.

get_overlay_exposure

• It uses the same route and the same 30 s budget as cpz-py client.overlays.exposure().
• The result leads with the verdict, then gives the platform document under data: {complete, hedge_ratio_status: measured | not_measured | withheld, hedge_ratio_reason, withheld?, data}.
• complete: false adds a withheld block. It lists the missing prices and history and tells the model not to size or place a hedge from the result.
• Whenever complete is false, hedge.current_ratio, drift, outside_band and suggested_order are forced to null. The platform already withholds them. If a drifted upstream sends numbers anyway, they are removed and the event is logged. A ratio computed from part of a book can never reach a model as a number.
• not_measured is distinct from withheld. It covers objectives with no ratio (fx, duration, tail, custom, vol_target) and a target book with nothing to hedge. None of these cases is reported as zero.
• Errors come through with their real status: 404, 409 not_an_overlay / overlay_not_configured, 502, and 503 market_data_unconfigured. The 409s get guidance pointing at configure_overlay and list_overlays.
• A 200 with no boolean complete, no hedge block or no targets list is refused as invalid_upstream_response.

configure_overlay

• It sends PUT /overlays/{id} with {role, policy, targets}, or {role: "alpha"} alone to remove the configuration.
• role: "overlay" replaces the whole policy and the whole target list. The description says so, and tells the model to read list_overlays first. It also says that becoming an overlay turns short selling on.
• Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true. Compact mode advertises it by name, and call_tool refuses it (not_dispatchable).
• Client-side refusals happen before any request. The policy and target objects are strict, so a misspelt field (for example hedge_ration) is refused rather than dropped and silently replaced by the database default. It refuses:
  • an unknown objective or rebalance trigger;
  • hedge_ratio outside 0 to 5, or tolerance_band outside (0, 1];
  • a beta objective without benchmark_symbol;
  • a missing policy, or no targets;
  • a self-target, or the same target twice (broker and account key normalised as the database trigger does);
  • a weight outside (0, 10], or an environment other than paper or live;
  • policy or targets passed with role alpha.
• Only the fields given are sent, so any defaults are the database's own. Symbols are sent upper-case.
• Ownership, account membership and cycles can only be checked by the platform. Its 400 invalid_overlay_config message is passed through verbatim in message and in the text content. 404 not_found_or_not_owned and 409 duplicate_target come through as errors.
• Never reports a failed save as a save:
  • A 5xx or a timeout carries operation_outcome: "unknown", with guidance to check before saving again. The PUT is not retried.
  • A 200 whose body has no saved object or no overlay key is refused as invalid_upstream_response, also with outcome unknown.
  • A 200 with overlay: null and read_back_error is reported as saved, with a note to confirm it with list_overlays.
• Failures are logged with request id, strategy id, role, status and error code.

Plumbing

• callRestApi gains api: 'gateway', with base CPZ_GATEWAY_BASE_URL (default https://api-ai.cpz-lab.com/cpz). It sends the same headers, timeout, retry policy and request id. Retries stay GET-only.
• All three tools are added to TOOL_SCOPES (strategies) and the strategies category. OUTPUT_SCHEMAS covers the two reads, whose envelopes this server builds; configure_overlay declares none, like the other writes that proxy to their own handlers.
• The guide resources (tool-usage, permissions), README and tool-catalog.json are updated. The catalogue goes from 31 to 34 tools, and compact from 15 to 16 (it gains configure_overlay). A data key still sees 10.

Tests

• npm test: 225 passed across 10 files. The baseline on origin/main was 163 passed.
  • tests/overlay-tools.test.ts has 61 tests. tests/api-client.test.ts gains one gateway routing test. The pinned counts are updated.
• npm run build and tsc --noEmit are clean.
• HTTP is mocked throughout. The tests cover:
  • the exact gateway URLs, methods, credential and request-id headers, and PUT bodies;
  • exposure complete, incomplete, not-measured and upstream-drift cases, plus the 404/409/503/403 errors;
  • the list: success, empty, truncated, unreadable 200s, and 502/403;
  • configure success, alpha removal, only-given-fields, read-back failure reported as saved, the verbatim 400 message, 404/409/403, a 502 not retried with outcome unknown, and an unreadable 200 not reported as a save;
  • 9 cross-field refusals and 15 schema refusals, all before HTTP;
  • scope filtering, and compact-mode search, dispatch and the write refusal.
• Mutation checks: removing the client-side validation, the unreadable-200 guard or the list shape guard fails 11 tests. Removing the exposure withholding, the not-configured branch or the strategy_role guard in the first commit failed 3. The code was restored each time.

Not verified

• No call was made against production. There was no credential, by instruction. The route shapes come from origin/feat/overlay-config-api (supabase/functions/_shared/overlay-config.ts, the cpz gateway route and migration 20260927180000). The coordinator reports cpzai#1736 merged, migrated and deployed.
• Not deployed. It ships through buildspec/ECS.

Follow-ups

• After deploy, export the catalogue to the platform docs: npm run export:catalog -- --output /path/to/cpzai/src/lib/mcp-tool-catalog.json.
• The GitHub remote reports this repository moved to CPZ-Lab/cpzai-mcp-server. Local remotes still point at the old name.

🤖 Generated with Claude Code