StableOps
Agent

MCP Server

给 Agent 暴露受控的查询与低风险动作。

@stableops/mcp-server 是一个基于 stdio 的 MCP 服务器，把 StableOps SDK 暴露成一组固定的工具。AI Agent（Claude Desktop、Cursor 以及任何兼容 MCP 的 host）只能调用这些工具，不能直接访问 API，且每次调用都会受 工作区的 Agent 策略 约束。

工具集

MCP 工具按资源族分组。所有工具都会先经过 /v1/agent/actions，只读工具通常自动放行，写入工具受白名单和审批开关约束。

Payment Orders

工具类型说明
list_payment_orders只读列出支付单。
get_order只读按 id 查询单笔支付单。
create_payment_order写入创建支付单。
cancel_payment_order写入取消支付单。

Addresses

工具类型说明
get_address_pools只读查询地址池配置。
list_addresses只读列出可用或已分配地址。
import_addresses写入批量导入地址。
update_address写入更新地址状态或备注。
remove_address写入移除地址。

Webhooks

工具类型说明
list_webhook_endpoints只读列出 Webhook 端点。
create_webhook_endpoint写入创建 Webhook 端点。
update_webhook_endpoint写入更新 Webhook 端点。
rotate_webhook_secret写入轮换端点签名密钥。
list_webhook_deliveries只读读取最近的 Webhook 投递记录。
replay_webhook_delivery写入重放单条投递。
replay_webhook_dead_letters写入重放死信队列。

Checkout Sessions

工具类型说明
create_checkout_session写入创建托管收银台 Session。

Agents

Agent 分组只暴露只读工具和 request_action_approval。MCP 不暴露 upsert_agent_policy、approve_agent_action、reject_agent_action 或 revoke_agent_session，避免 Agent 修改或批准自己的护栏。

工具类型说明
list_agent_sessions只读列出 Agent 会话。
get_agent_policy只读查询当前策略。
list_agent_actions只读查询 Agent 动作审计记录。
request_action_approval写入登记一个自定义审批请求；它不执行 StableOps API，只进入审批/审计流。

Merchant Subscriptions

工具类型说明
list_merchant_plans只读列出订阅套餐。
create_merchant_plan写入创建订阅套餐。
update_merchant_plan写入更新订阅套餐。
delete_merchant_plan写入删除订阅套餐。
create_merchant_subscription写入创建商户订阅。
list_merchant_subscriptions只读列出商户订阅。
get_merchant_subscription只读查询订阅详情。
get_merchant_subscription_by_user只读按用户查询订阅。
change_merchant_subscription_plan写入变更订阅套餐。
cancel_merchant_subscription写入取消订阅。
resume_merchant_subscription写入恢复订阅。
list_merchant_invoices只读列出订阅账单。
get_merchant_invoice只读查询账单详情。
pay_merchant_invoice写入支付订阅账单。
get_merchant_invoice_payment_status只读查询账单支付状态。
get_merchant_subscription_settings只读查询订阅设置。
update_merchant_subscription_settings写入更新订阅设置。
create_merchant_portal_session写入创建 Portal 会话。
revoke_merchant_portal_session写入撤销 Portal 会话。

只读工具默认 auto_allowed。写入工具一律先打 POST /v1/agent/actions；如果策略 配置了 require_approval=true，会返回 pending_approval，Agent 必须等人工在 dashboard 上批准。

安装与配置

先全局安装 @stableops/mcp-server，使 stableops-mcp 命令在本机可用：

pnpm add -g @stableops/mcp-server

安装只负责让 stableops-mcp 命令在本机可用。日常接入时无需另开终端手动启动； Claude Desktop、Cursor、Codex CLI、OpenCode 等 MCP host 会根据配置自动启动并管理 这个 stdio 子进程。

需要在 MCP host 的配置中提供以下环境变量：

变量必填默认说明
STABLEOPS_API_KEY是—作为 Authorization: Bearer … 发送。环境（sandbox / live）由 key 自身决定。
STABLEOPS_AGENT_SESSION_ID是—把这个 MCP 进程绑到一个可审计的 session。
STABLEOPS_API_URL否https://api.stableops.dev覆盖 API 基础地址（自部署或测试场景使用）。

获取 Session ID

推荐在 Dashboard 中创建：

  1. 打开 Dashboard → Agent，确认当前环境是 API Key 将使用的环境（Sandbox 或 Live）。
  2. 在“会话”区域点击“创建 Session”，可填写标签和过期时间。
  3. 创建成功后复制页面显示的 Session ID，填入 MCP host 的 STABLEOPS_AGENT_SESSION_ID。

Session ID 必须和 MCP 使用的 STABLEOPS_API_KEY 属于同一个组织和环境，否则所有工具都会返回 agent session not found。

自动化部署也可以调用 POST /v1/agent/sessions 创建 session，然后使用响应中的 id：

curl -X POST https://api.stableops.dev/v1/agent/sessions \
  -H "authorization: Bearer $STABLEOPS_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"label":"production-mcp"}'

客户端配置示例

所有 host 关心的都是同样三件套：启动命令 stableops-mcp、没有额外参数，以及上面那份 env。区别只在配置文件路径和字段命名。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "stableops": {
      "command": "stableops-mcp",
      "env": {
        "STABLEOPS_API_KEY": "sk_sandbox_xxx",
        "STABLEOPS_AGENT_SESSION_ID": "agent_sess_01"
      }
    }
  }
}

Claude Code (CLI)

一行 CLI 注册，默认只对当前项目生效；去掉 -s user 则改为全局：

claude mcp add stableops -s user -- stableops-mcp \
  -e STABLEOPS_API_KEY=sk_sandbox_xxx \
  -e STABLEOPS_AGENT_SESSION_ID=agent_sess_01

或者直接编辑 ~/.claude.json，在 mcpServers 里写一份与 Claude Desktop 同形 JSON。

Codex CLI

~/.codex/config.toml（Codex 用 TOML 而非 JSON）：

[mcp_servers.stableops]
command = "stableops-mcp"
env = { STABLEOPS_API_KEY = "sk_sandbox_xxx", STABLEOPS_AGENT_SESSION_ID = "agent_sess_01" }

opencode

~/.config/opencode/opencode.json（或项目根 opencode.json）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "stableops": {
      "type": "local",
      "command": ["stableops-mcp"],
      "environment": {
        "STABLEOPS_API_KEY": "sk_sandbox_xxx",
        "STABLEOPS_AGENT_SESSION_ID": "agent_sess_01"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目内）：

{
  "mcpServers": {
    "stableops": {
      "command": "stableops-mcp",
      "env": {
        "STABLEOPS_API_KEY": "sk_sandbox_xxx",
        "STABLEOPS_AGENT_SESSION_ID": "agent_sess_01"
      }
    }
  }
}

VS Code（GitHub Copilot Agent）

.vscode/mcp.json：

{
  "servers": {
    "stableops": {
      "type": "stdio",
      "command": "stableops-mcp",
      "env": {
        "STABLEOPS_API_KEY": "sk_sandbox_xxx",
        "STABLEOPS_AGENT_SESSION_ID": "agent_sess_01"
      }
    }
  }
}

其它 host

Cline、Continue、Gemini CLI、Windsurf、Zed 等任何 MCP 客户端格式都一样： stdio command + 可选 args + env，把上面的字段照搬到它们各自的配置文件即可。

在自有 host 内嵌入

如果你自己写 Node host，可以直接构造 server，而不必启动二进制：

import { createAgentToolkitServer } from '@stableops/mcp-server'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

const server = createAgentToolkitServer({
  apiKey: process.env.STABLEOPS_API_KEY!,
  agentSessionId: 'agent_sess_01',
})

await server.connect(new StdioServerTransport())

一次工具调用的生命周期

agent ─▶ tool call ─▶ POST /v1/agent/actions
                       │
                       ├── decision = auto_allowed   ─▶ SDK 调用 ─▶ POST /actions/:id/executed
                       └── decision = pending_approval ─▶ 阻断响应
                                                          │
                                                          （人工在 dashboard 批准后，
                                                           Agent 重新发起 tool call）

工具返回结构化结果（符合 outputSchema）或 isError 信封。结构化字段与 SDK 对应资源接口返回的格式一致：camelCase 键名，枚举值与 /v1/payment-orders 完全相同。

安全边界

  • Agent 不能发起链上交易。StableOps 本身不持有私钥，无法主动签名或发送交易；即 使调用 create_payment_order 也只是创建收款请求，实际链上转账由付款方自行发起。 confirmed 等状态来自链上扫描结果，不通过任何 API 控制。
  • Agent 不能绕过策略。即使只读工具也会经过 /v1/agent/actions，session 被吊销后 所有调用立即失败。
  • 写入工具受策略白名单和 require_approval 开关控制，即便被 prompt injection 诱导， 触及审批范围的调用最多落到 pending_approval，需人工在控制台批准后才会生效。

下一步

这篇文档怎么样？

最后更新

订阅

创建套餐、为商户用户开通订阅、生成账单，并让终端用户通过托管收银台或你的自有钱包流程支付。

Agent 策略

Agent 动作的工具白名单与审批闸门。

本页内容

工具集Payment OrdersAddressesWebhooksCheckout SessionsAgentsMerchant Subscriptions安装与配置获取 Session ID客户端配置示例Claude DesktopClaude Code (CLI)Codex CLIopencodeCursorVS Code（GitHub Copilot Agent）其它 host在自有 host 内嵌入一次工具调用的生命周期安全边界下一步