MCP 服务器
位于 https://api.dcision.io/mcp 的 Dcision MCP 服务器——身份验证、十四个工具及其输入与输出、错误,以及在 Claude Code、Cursor、VS Code、Claude Desktop、Codex、Gemini CLI 和 curl 中的配置。
Endpoint https://api.dcision.io/mcp
Transport Streamable HTTP (stateless, JSON responses)
Auth Authorization: Bearer dcs_live_… | dcs_test_…Model Context Protocol 服务器让 AI 智能体和编程助手可以使用 Dcision:列出你的决策、读取它们的契约、检查和运行状态、读取执行记录、浏览模板以及校验决策 schema。它是 Dcision API 的一部分——与 REST API 使用相同的密钥、相同的限制、相同的计费。
关于在 Claude Code 中配合 Dcision skill 进行分步设置,请参见在 Claude Code 中使用 Dcision。
身份验证
在每个请求中以 Bearer token 的形式发送工作区的 API 密钥。服务器不保留会话,也不存储凭据:每个请求都单独进行身份验证,工具作用于密钥所属的工作区。
- 没有密钥、密钥格式错误或已撤销 → HTTP
401,带有WWW-Authenticate: Bearer请求头和一条说明在哪里创建密钥的消息。 - 只接受 API 密钥——绝不接受来自应用的会话。
- 实验时优先使用
dcs_test_…密钥:运行是真实的并计入用量,但目的地会以livemode: false投递。
限制与计费
| 每个请求 | 计入读取类速率限制窗口,与 GET /v1/me、GET /v1/decisions 和 GET /v1/executions 共享。读取不计费。 |
run_decision | 还会计入决策窗口,与 POST /v1/decisions/{slug} 共享。与 API 调用一样计费,使用相同的配额。 |
| 请求 | 仅限 POST /mcp。GET /mcp 和 DELETE /mcp 返回 405:没有会话,也没有服务器发送事件流。 |
| 请求体大小 | 最多 1 MB,因此 validate_schema、create_decision 和 update_decision 可以接受大型 schema(智能体提示词最多 32,000 个字符)。check_state 和 run_decision 的 state 仍限制为 128 KB(INVALID_STATE)。更大的请求体返回 413 PAYLOAD_TOO_LARGE。 |
工具
每个工具都以 JSON 返回其结果——既作为结果 content 中的文本,也作为 structuredContent。读取类工具标注为 readOnlyHint: true。run_decision、create_decision、update_decision 和 deploy_decision 既不标注为只读也不标注为幂等,deploy_decision 还被标注为破坏性操作(它会改变生产环境运行的内容),以便客户端在调用它们之前进行询问。
| 工具 | 只读 | 参数 | 返回 |
|---|---|---|---|
get_account | 是 | — | 密钥所属的工作区、密钥本身、套餐和本周期的用量——即 GET /v1/me 的响应体。 |
list_decisions | 是 | — | 工作区的决策及其 slug、名称、状态和当前生效版本——即 GET /v1/decisions 的响应体。 |
get_decision | 是 | slug | 某个决策的契约——状态 schema、问题及其选项、行动、fallback 行动和示例状态——即 GET /v1/decisions/{slug} 的响应体。 |
check_state | 是 | slug、state | { "valid": true },或 { "valid": false, "message" },附带运行会以 422 INVALID_STATE 失败的原因。检查当前生效版本的状态 schema 和状态自身的 token 限制;不会运行任何内容。当状态加上最长的问题超出引擎的 token 预算时,运行仍可能返回 422。 |
run_decision | 否——计费 | slug、state,可选 include_probabilities(boolean) | 决策的响应,与 POST /v1/decisions/{slug} 返回的相同。 |
list_executions | 是 | 可选 decision(slug)、status(success 或 error)、limit(1–100,默认 20)、cursor | 最近的执行记录,从不包含输入——即 GET /v1/executions 的响应体。 |
list_templates | 是 | — | { "data": [...] },包含每个模板的 id、name、description、category 和 patterns。 |
get_template | 是 | id | 模板的摘要,加上 schema 中完整的决策 schema 和一个 sample_state。 |
validate_schema | 是 | schema(object) | { "valid": true, "schema" } 及规范化后的 schema——已添加 other、已填入默认值——或 { "valid": false, "issues": [{ "path", "message" }] }。规则与编辑器和 API 相同。 |
create_decision | 否 | name(1–80)、schema(object),可选 slug、description(≤ 500) | 创建一个草稿决策。返回带有 slug 和 status: "draft" 的决策。计入套餐的决策数量上限(PLAN_LIMIT_REACHED)。 |
update_decision | 否 | slug,可选 schema、name、description | 替换草稿 schema 和/或重命名决策。在 deploy_decision 之前,运行的内容不会改变。 |
deploy_decision | 否——破坏性 | slug | 把草稿发布为新版本:之后的运行都会使用它。 |
list_workspaces | 是 | 可选 external_id、limit(1–100)、cursor | 合作伙伴模式:你的子工作区及其限额和用量——即 GET /v1/workspaces 的响应体。 |
upsert_workspace | 否 | external_id、name,可选 seed_decisions(slug 列表)、deploy(boolean) | 合作伙伴模式:创建客户的子工作区(或为其重命名),可选择把已部署的决策复制进去。 |
每个工具都会在 tools/list 中发布其确切的输入 schema:构建你自己的客户端时请在那里查阅。
在子工作区中操作
合作伙伴使用自己的 API 密钥并发送请求头 Dcision-Workspace: ext:<external_id>(或子工作区的 id):之后每个工具都会在该客户的子工作区中读取、运行、创建和部署,而速率限制仍属于你的工作区。属于其他工作区的子工作区会返回 404(JSON-RPC 错误 -32004)。
claude mcp add --transport http dcision-acme https://api.dcision.io/mcp \
--header "Authorization: Bearer $DCISION_API_KEY" --header "Dcision-Workspace: ext:acme"运行决策
常规流程,Dcision skill 会把它教给智能体:
list_decisions——选择一个status为deployed的决策。get_decision——读取state_schema,并从example_state开始。check_state——修正状态直到通过;这不产生任何费用。run_decision——运行一次,然后根据action行动。
run_decision 以与 API 相同的方式发送状态:对象、字符串或数组,取决于决策的状态类型。它没有幂等键:每个到达引擎的调用都会运行并计费。如果调用因网络失败,请先用 list_executions 查找该次运行,再重试。若需要从机制上保证安全的重试,请带上 Idempotency-Key 调用 REST API。
编写决策
智能体可以端到端地构建一个决策:
get_template——有合适的模板时从模板开始。validate_schema——修正 schema 直到没有问题。create_decision——将其创建为草稿。update_decision——在草稿上迭代;生产环境不会有任何变化。deploy_decision——发布它。在这一步之前请先询问用户。
写入操作以创建该 API 密钥的人的名义进行;没有作者的密钥会被拒绝(FORBIDDEN)。删除或停用决策、团队、目的地密钥和计费仍在应用中进行。
错误
| 位置 | 你会得到什么 |
|---|---|
| HTTP + JSON-RPC 错误 | 没有有效 API 密钥时为 401(带 WWW-Authenticate: Bearer),读取窗口用完时为 429,POST 以外的任何方法为 405,没有 Accept: application/json, text/event-stream 时为 406,JSON-RPC 批量请求为 400(每个请求发送一条消息)。响应体是一个 JSON-RPC error,其 message 说明应该怎么做。完全不是 JSON 的请求体会得到 API 自身的 400 INVALID_REQUEST 错误对象。 |
| 工具结果 | isError: true 以及以文本形式返回的 { "error": { "code", "message", "details" } },用于 API 会以错误回复的所有情况——DECISION_NOT_FOUND、DECISION_NOT_DEPLOYED、INVALID_STATE、CREDITS_EXHAUSTED、SPEND_CAP_REACHED、QUOTA_EXCEEDED、run_decision 上的 RATE_LIMITED、引擎错误——也用于未知工具(NOT_FOUND)或无效参数(INVALID_REQUEST,每个问题列在 details 中)。参见错误。 |
智能体应该阅读错误的 message——它会说明需要修正什么——并且不要原样重试 4xx。
Claude Code
claude mcp add --transport http dcision https://api.dcision.io/mcp \
--header "Authorization: Bearer $DCISION_API_KEY" \
--scope user去掉 --scope user 即可只添加到当前项目,或者提交一个从每个人的环境中读取密钥的 .mcp.json:
{
"mcpServers": {
"dcision": {
"type": "http",
"url": "https://api.dcision.io/mcp",
"headers": { "Authorization": "Bearer ${DCISION_API_KEY}" }
}
}
}更多内容请参见在 Claude Code 中使用 Dcision。
其他客户端
任何支持通过 Streamable HTTP 连接远程服务器并能设置自定义请求头的 MCP 客户端都可以连接。
{
"mcpServers": {
"dcision": {
"url": "https://api.dcision.io/mcp",
"headers": { "Authorization": "Bearer ${env:DCISION_API_KEY}" }
}
}
}- Cursor——所有项目使用
~/.cursor/mcp.json,或在仓库中使用.cursor/mcp.json。 - VS Code——
.vscode/mcp.json;VS Code 会询问一次密钥并安全地保存它。 - Claude Desktop——Settings → Developer → Edit Config(
claude_desktop_config.json)。Claude Desktop 通过mcp-remote连接远程服务器,这是一个需要 Node.js 的社区桥接工具;请求头通过环境变量传入,这样Bearer后面的空格在所有平台上都能保留。编辑后请重启 Claude Desktop。 - Codex——
~/.codex/config.toml,并在运行 Codex 的地方导出DCISION_API_KEY。 - Gemini CLI——
~/.gemini/settings.json,或项目中的.gemini/settings.json。
ChatGPT 和 claude.ai
ChatGPT 和 claude.ai 中的连接器使用 OAuth 登录,而 Dcision MCP 服务器目前还不提供 OAuth:它只接受请求头中的 API 密钥。请使用上面的客户端之一,或使用 REST API。
用 curl 调用服务器
服务器通过 HTTP 使用普通的 JSON-RPC 2.0,并且是无状态的——无需 initialize 握手。发送 Content-Type: application/json 和 Accept: application/json, text/event-stream:
curl -s https://api.dcision.io/mcp \
-H "Authorization: Bearer $DCISION_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'使用 tools/call 加上工具的 name 和 arguments 来调用工具:
curl -s https://api.dcision.io/mcp \
-H "Authorization: Bearer $DCISION_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": { "name": "get_decision", "arguments": { "slug": "lead-qualification" } }
}' | jq '.result.structuredContent'回复是一个 JSON-RPC 响应:result.content[0].text 以文本形式保存工具的 JSON,result.structuredContent 以对象形式保存相同的值(节选):
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"content": [{ "type": "text", "text": "{\"slug\": \"lead-qualification\", \"status\": \"deployed\", \"version\": 3}" }],
"structuredContent": { "slug": "lead-qualification", "status": "deployed", "version": 3 }
}
}在没有配置 MCP 客户端时,Dcision skill 也是这样访问 validate_schema、check_state 和模板的。
安全
- 服务器只作用于密钥所属的工作区;密钥无法访问其他工作区的决策。
- 工具从不返回过往执行的输入、密钥、目的地配置(URL、请求头)或决策的完整 schema——只返回其当前生效版本的契约。
run_decision和list_executions的结果确实包含每次运行的destinations条目,其中可能带有从状态映射而来的值(函数参数、LLM 或智能体的回复):请像对待任何决策输出一样对待它们。 - 像对待任何生产环境密钥一样对待智能体使用的密钥:把它保存在环境变量中,实验时限定为 test 密钥,如果泄露请在 API 密钥中撤销它。