CPZAI

CPZAI MCP 服务

CPZAI 的模型上下文协议适配器，涵盖策略、已保存的回测、经纪商账户、订单、投资组合持仓、市场数据、风险、提供商连接和中台报告。

托管端点： https://mcp.cpz-lab.com/mcp 传输方式： 无状态 Streamable HTTP 当前源代码： 版本 1.4.0：34 个工具、3 个指南资源、2 个工作流提示词。

此 README 描述的是更新后的源代码，而非已完成的生产部署。请使用已连接客户端的 tools/list、resources/list 和 prompts/list 验证已部署的功能。之前的源代码注册了 21 个工具；关于 18 个工具或计划发布 29 个工具的旧说法并不准确。

连接

在 CPZAI 的 设置 → API 密钥 中创建密钥和密文。在支持带自定义标头的远程 MCP 的客户端中，配置：

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

如果客户端的配置格式不同，请使用相应的连接器设置。支持 OAuth 的客户端可以连接到同一个 MCP URL，并使用 PKCE S256 完成登录。发现端点：

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

OAuth 访问令牌是不透明的，本服务接受此类令牌。请勿将其直接传递给 REST API。旧版 Bearer cpz_key_…SECRET 凭据默认已禁用；请使用标头身份验证或 OAuth。

工具目录

领域	工具	用途
策略	list_strategies	状态、策略类型、标题
策略	get_strategy	读取一项策略
策略	create_strategy	创建一项策略
策略	update_strategy	更新选定的策略字段
覆盖策略	list_overlays	列出覆盖策略及其完整对冲政策和目标
覆盖策略	get_overlay_exposure	查看一项覆盖策略的敞口、对冲偏差、建议订单、有效性和损益
覆盖策略	configure_overlay	原子化设置或移除覆盖策略的角色、政策和目标
回测	get_backtest_results	列出已保存的回测运行
回测	get_backtest_result	读取一项已保存的回测运行
订单	list_orders	状态、标的、方向、策略 ID
订单	get_order	读取一条 CPZ 订单记录
订单	place_order	向选定的已连接账户提交订单
投资组合	list_positions	账户 ID、标的
投资组合	sync_portfolio	同步已连接的经纪商投资组合
账户	list_accounts	经纪商、环境、是否可交易
连接	list_connections	连接类型
连接	create_connection	存储加密的提供商凭据
数据文件	list_data_files	名称、状态、文件类型
数据文件	get_data_file	读取已上传文件的元数据
市场数据	get_market_data	获取标的的当前报价
市场数据	get_bars	获取历史 OHLCV K 线
风险	compute_risk	计算并存储最新风险快照
风险	list_risk_snapshots	账户 ID
风险	get_risk_snapshot	读取一项已保存的风险快照
执行	execute_strategy	执行策略代码；可能会下单
中台	list_deals	实体 ID、基金、账簿、交易 ID、产品类型、状态
中台	list_lifecycle_events	实体 ID、交易 ID、类型、状态、起始时间、结束时间
中台	list_cash_flows	实体 ID、交易 ID、基金、账簿、起始时间、结束时间、未结算
中台	list_journal_entries	实体 ID、交易 ID、起始时间、结束时间
中台	list_fund_periods	实体 ID、基金、状态
日常	list_watchlist	你的观察列表，最多 10 个标的
日常	add_to_watchlist	标的
日常	remove_from_watchlist	list_watchlist 返回的 ID
日常	export_transactions	年份或起始/结束时间、账户 ID、标的、方向、环境、经纪商、策略 ID
日常	cash_summary	经纪商、环境、是否可交易
Webhook	list_webhooks	是否启用
Webhook	create_webhook	订阅事件的 HTTPS 端点
Webhook	delete_webhook	移除 Webhook 订阅
个人资料	get_profile	读取已认证的个人资料

表中的筛选条件均为可选项。单条记录工具需要提供相应列表工具返回的 CPZ 记录 UUID。get_order 接受的是 CPZ 记录 ID，而非经纪商订单 ID。读取文件时会返回元数据；不会下载文件内容或示例行。回测工具读取已保存的运行记录，不会启动回测。

分页与数据

所有列表工具都接受 limit（整数，范围为 1–100）和 offset（非负整数，默认值为 0），以及其公开架构中列出的任何排序字段。默认 limit 为 50，list_accounts 除外，其默认值为 100。分页时请明确指定 limit。REST 中的 count 表示当前页的条目数，而非总数。返回的条目数少于 limit 之前，请继续分页，然后再报告完整的投资组合。

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

获取同一列表的下一页时，请使用 {"limit":100,"offset":100}。上游错误不代表最后一页为空。

get_bars 接受 symbols、timeframe、start、end、limit（每个标的 1–10,000 根 bar）和 feed（iex 或 sip，具体取决于服务提供商的权限）。支持的时间周期有 1Min、5Min、15Min、30Min、1Hour、2Hour、4Hour、1Day、1Week 和 1Month。

中台列表支持可选的 entity_id，用于在调用者是活跃成员时访问实体账簿；否则会使用个人账簿。请保留以最小货币单位表示的小数字符串，作为精确值处理，不要将其转换为 JavaScript 数字。

交易与副作用

选择账户前，请使用 list_accounts 检查 environment 和 tradable。tradable: true 会筛选可路由的账户；值为 false 或省略时则包含所有账户。账户发现支持的服务提供商多于订单路由。实盘或模拟盘执行取决于所选账户和平台控制。

place_order 要求数量为正数。限价单／限价止损单需要 price；止损单／限价止损单需要 stop_price。目前只公开 time_in_force: "day"，因为旧版路由仅支持该有效期。支持的订单类型仍取决于经纪商。execute_strategy 可以下单，并非信号预览或模拟运行。只有在用户授权交易时，才可调用这些工具。

工具注释用于说明副作用。实际授权由 REST API 根据密钥、订阅、所有权和资源范围检查来执行。旧版 read／write／trade 权限会由该 API 扩展为资源范围。

叠加策略

叠加策略是一种根据对冲政策对冲其他策略或整个经纪账户的策略。所有三个叠加策略工具都会使用你自己的凭据调用 cpz 网关，并需要 strategies 范围。

list_overlays（GET /cpz/overlays）会在一次读取中返回所有叠加策略的完整政策（目标、对冲比率、容差区间、对冲工具、基准、再平衡触发条件、备注）和目标，不包含市场数据。当叠加策略有政策且至少有一个目标时，configured 为 true。平台最多返回 200 个叠加策略，并按标题排序；truncated: true 表示还有更多结果，此时结果会附带说明，指出列表并不完整。

get_overlay_exposure（GET /cpz/overlay/exposure）会解析单个叠加策略的对冲情况。结果首先给出判定：complete、hedge_ratio_status（measured、适用于没有比率目标或没有对冲对象的 not_measured，或 withheld）以及 hedge_ratio_reason，随后是 data 中的平台文档。当 complete 为 false 时，表示缺少价格或价格历史记录；此时对冲比率、偏离度、区间标志和建议订单均为 null，并会在 withheld 块中列出缺失的代码。切勿根据不完整结果确定对冲规模或执行对冲。建议订单仅供参考；下单需要另行调用经用户授权的 place_order。409 表示该策略不是叠加策略，或尚无政策或目标，并会指向 configure_overlay。

configure_overlay（PUT /cpz/overlays/{id}）会在一个事务中保存角色、政策和目标，并返回已保存的配置。

• role: "overlay" 需要政策和至少一个目标，并会替换两者。省略的政策字段会使用默认值（hedge_ratio 为 1，tolerance_band 为 0.1，rebalance_trigger 为 band，无工具、无备注）；未列出的目标会被移除。请先读取 list_overlays，再发送完整配置。
• role: "alpha" 会移除政策和目标。使用此角色时，两者都不要传入。
• 策略转为叠加策略后，会启用卖空功能。
• 工具会在发送任何请求之前拒绝以下情况：目标类型未知、hedge_ratio 超出 0 到 5、tolerance_band 超出 (0, 1]、beta 叠加策略缺少 benchmark_symbol、没有目标、目标指向自身、同一目标出现两次、权重超出 (0, 10]、账户环境不是 paper 或 live，以及字段拼写错误。平台会检查所有权、账户成员关系和循环依赖；其 400 错误消息会原样传递。
• 如果读取回查失败，200 响应仍会报告已保存，并提示使用 list_overlays 确认。对于 5xx、超时或无法读取的 200，绝不会报告已保存：结果状态未知，因此请先检查 list_overlays，再决定是否重新保存。写入操作绝不会重试。

结果和错误

工具响应会保留可读的 JSON 文本，并包含结构化内容。大多数读取工具都会声明 outputSchema，以便客户端验证返回内容：列表路由返回 {data, count}，单条记录路由返回 {data}，删除操作返回 {message}。代理到其他服务的操作工具（execute_strategy、sync_portfolio、compute_risk、get_market_data、get_bars）以及由各自处理程序处理的写入操作（place_order、create_connection、configure_overlay）不会声明输出架构，因为本服务无法保证这些工具的返回结构。错误结果会跳过输出验证。使用结果前请检查 isError。格式错误的上游响应和提供方故障仍会作为错误处理。请求 ID 可用于追踪，且不会记录凭据。

符合条件的 GET 调用可在有界超时时间内重试暂时性上游故障。写入操作不会自动重试。提交订单后发生超时，意味着结果尚未确认；重试前请检查现有订单和经纪账户。公开订单路由不提供通用的端到端幂等性保证。

资源和提示词

类型	名称	用途
资源	cpzai://guides/tool-usage	工具选择、分页和能力边界
资源	cpzai://guides/permissions	资源权限和执行边界
资源	cpzai://guides/discovery	端点、延迟加载和搜索约定
提示词	review_portfolio	投资组合审查工作流；account_id 为可选项
提示词	analyze_strategy	策略调查；strategy_id 为必填项

请求提示词会返回指令；不会执行工作流。请使用标准 MCP 方法发现这些内容。没有 /mcp/info 端点。

渐进式工具发现

完整目录包含 34 个工具和约 40 KB 的 JSON Schema，除非客户端能够延迟加载工具，否则每次请求都要承担这部分开销。当模型需要从约 30 个以上的工具中进行选择时，工具选择准确率也会下降。这里有两个端点，以不同的发现模式提供相同的工具。

POST /mcp：完整目录

tools/list 会返回所有工具。客户端自行延迟加载时使用此端点：客户端需要先获取工具定义，才能延迟加载。使用 Claude 的 MCP 连接器时，将 defer_loading 与工具搜索工具配合使用，并让日常读取工具保持已加载状态：

{
  "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 }
  }
}

延迟加载的定义仍会在每次请求中发送；在搜索发现这些定义之前，它们不会进入模型上下文，而且提示词前缀不会改变，因此缓存可以继续使用。Claude Code 会在此端点上应用自己的工具搜索，无需配置。

POST /mcp/compact：服务端发现

适用于没有自身延迟加载机制的客户端。tools/list 会返回 16 个工具，而不是 34 个（约 18 KB，而不是 40 KB，减少 56%）：

• search_tools：自然语言或关键字查询，可选 category，返回每个匹配项的完整输入 schema。搜索工具名称、标题、描述、参数名称和参数描述，因此像 unsettled 或 entity_id 这样的字段名称也能找到接受该字段的工具。类别：strategies、backtests、orders、positions、accounts、market-data、risk、data、webhooks、middle-office、profile。
• call_tool：通过工具名称和与其 input_schema 匹配的参数对象调用已发现的工具，并原样返回该工具的结果。
• 每个会更改状态的工具（place_order、execute_strategy、create_strategy、update_strategy、create_connection、create_webhook、delete_webhook、sync_portfolio、compute_risk、configure_overlay），以及读取锚点 list_accounts、list_positions、list_orders、get_market_data。

call_tool 仅分发只读工具。客户端会根据可见的工具名称进行审批，因此通过通用分发器路由订单会使其无法被旨在拦截订单的检查发现。它也会拒绝已经公开的只读工具；对于未知名称，则会提供相近匹配项，而不是猜测。分发前会根据真实工具 schema 验证参数；若遭拒，会返回有问题的路径以及该工具的 schema。

协议修订版本

两个端点都通过同一个 URL 提供 2026-07-28 修订版本及所有更早的版本，最早可追溯至 2024-10-07。

• 2026-07-28 客户端会单独发送每个请求，不进行 initialize 握手；在 Mcp-Method 标头中指定方法（并在 Mcp-Name 中指定工具），以便网关无需解析请求正文即可路由；客户端的协议版本、客户端信息和能力则放在 _meta 中。
• server/discover 一次调用即可返回能力、说明和支持的版本。
• tools/list、prompts/list、resources/list 和 server/discover 都带有 ttlMs 和 cacheScope。tools/list 始终为 private：它会根据凭据进行筛选，因此共享缓存会把一个密钥的目录提供给另一个密钥。
• 使用 initialize 的客户端会像以前一样协商 2025-11-25、2025-06-18 或更早的版本。Claude Code 和现有连接器不受影响。

两个时期的服务端都是无状态的：没有会话、没有 Mcp-Session-Id，每个请求都会创建一个全新的服务端。

按范围发现

tools/list 仅包含调用凭据的范围所允许使用的工具。data 密钥可见 13 个工具，而不是 39 个；orders_paper 密钥（交易仅限模拟账户）可见订单相关工具，但看不到 execute_strategy、list_accounts 或中台工具；仅含身份验证范围的 OAuth 令牌只能看到 get_profile；search_tools 不会返回范围之外的工具，call_tool 也不会分发此类工具。范围来自 REST API 的 GET /me，按凭据缓存 60 秒，并且仅在调用 tools/list 时查询，不会在调用工具时查询。

如果查询失败，或者 REST API 部署版本早于 scopes 字段，系统会公布完整目录并记录原因：未知不等于没有范围。筛选属于发现机制，而非强制执行。REST API 仍是唯一决定凭据可访问内容的组件，因此，即使某个工具已列出，它仍可能返回 403。

实测范围：

端点	完整范围	仅 data 范围
/mcp	34 个工具，约 40 KB	10 个工具，约 9 KB
/mcp/compact	16 个工具，约 18 KB	6 个工具，约 6 KB

两个端点的工具名称、参数、结果和分页完全相同。发现过程不会读取账户数据，也不会下单。

架构

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 和 src/overlay-tools.ts 负责定义公开的 MCP 模式；src/capabilities.ts 定义指南资源和工作流提示词；src/tool-registry.ts 将这些相同的模式作为数据保存，src/tool-search.ts 则将它们转换为精简界面，因此公布的目录与可分发的目录不会发生偏差。它们与内部 Simons 工具相互独立，也不会从共享的模式包中导入。服务端会代理到现有的 REST 适配器，而不会使用服务角色密钥查询用户数据。托管服务还支持经过身份验证的 Simons 聊天代理路由；这些路由不是额外的 MCP 工具。

本地开发

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

客户端会在 CPZ_API_BASE_URL 后附加 /v1。内置默认值已包含 /functions/v1/rest-api；将环境变量设置为不带路径的 API 域名是错误的。此服务不需要 CPZ_SERVICE_KEY。

变量	用途
PORT	HTTP 端口（默认值为 3001）
CPZ_API_BASE_URL	/v1 之前的 REST 适配器基址
CPZ_API_TIMEOUT_MS	上游请求超时预算（默认值为 20000 ms）
CPZ_GATEWAY_BASE_URL	overlay 工具的 cpz 网关基址（默认值为 https://api-ai.cpz-lab.com/cpz）
MCP_BASE_URL	OAuth 发现和重定向中使用的公共源
MCP_TOKEN_SECRET	用于加密 OAuth 令牌和注册信息的共享密钥
ALLOW_LEGACY_BEARER	仅当值为 true 时启用旧版明文 bearer 格式
SIMONS_UPSTREAM_URL	可选的 Simons 代理上游地址覆盖值
SENTRY_DSN	可选的错误报告

OAuth 注册信息、代码和令牌都包含加密状态。生产环境中的副本必须共享 MCP_TOKEN_SECRET。如果未设置，开发环境会使用每个进程随机生成的密钥，令牌无法在重启后保留，也无法在其他副本上解析。刷新令牌的有效期为 30 天；轮换不会使先前的刷新令牌失效。撤销底层 CPZ API 密钥即可移除访问权限。

验证和构建

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

测试涵盖注册、验证、路由、凭据、响应错误和 OAuth 行为。本地验证无需执行实际订单或策略。

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

范围和贡献

托管端点是受支持的用户连接方式。提供此仓库是为了保持透明并支持本地开发；目前不支持在生产环境中自行托管。托管基础设施由单独团队维护。

CI 会将 tool-catalog.json 与 MCP 发现结果进行比较，并检查 README 中是否列出了每个工具。使用 npm run export:catalog -- --output /path/to/cpzai/src/lib/mcp-tool-catalog.json 将同一快照导出到平台；其文档测试会检查公共工具表。

请确保公共架构、行为测试、README 和 CPZAI 的Agent 集成文档保持同步。在内部 Simons 工具或计划中的 SDK 查询、沙箱、补丁、取消或中台写入功能实现并通过公共路由测试之前，请勿宣传这些功能。

MIT © CPZ Capital Ltd.