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 会把它教给智能体:

  1. list_decisions——选择一个 status 为 deployed 的决策。
  2. get_decision——读取 state_schema,并从 example_state 开始。
  3. check_state——修正状态直到通过;这不产生任何费用。
  4. run_decision——运行一次,然后根据 action 行动。

run_decision 以与 API 相同的方式发送状态:对象、字符串或数组,取决于决策的状态类型。它没有幂等键:每个到达引擎的调用都会运行并计费。如果调用因网络失败,请先用 list_executions 查找该次运行,再重试。若需要从机制上保证安全的重试,请带上 Idempotency-Key 调用 REST API。

编写决策

智能体可以端到端地构建一个决策:

  1. get_template——有合适的模板时从模板开始。
  2. validate_schema——修正 schema 直到没有问题。
  3. create_decision——将其创建为草稿。
  4. update_decision——在草稿上迭代;生产环境不会有任何变化。
  5. 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:

.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 密钥中撤销它。

本页内容