StableOps
Agent

MCP Server

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

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

工具集

工具类型说明
get_order只读按 id 查询单笔支付单。
list_events只读查询规范化链上事件流。
list_webhook_deliveries只读读取最近的 Webhook 投递记录。
create_payment_order写入创建一笔新的支付单（受策略管控）。
request_action_approval写入把敏感动作排进人工审批队列。

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

启动服务器

pnpm add -g @stableops/mcp-server   # 或者用 npx 一次性运行

STABLEOPS_API_URL=https://api.stableops.dev \
STABLEOPS_API_KEY=sk_sandbox_xxx \
STABLEOPS_ORG_SLUG=demo \
STABLEOPS_ENVIRONMENT=sandbox \
STABLEOPS_AGENT_SESSION_ID=agent_sess_01 \
  stableops-mcp

所有变量都从进程环境读取：

变量必填默认说明
STABLEOPS_API_URL否http://localhost:3001自托管或沙盒时覆盖。
STABLEOPS_API_KEY是—作为 Authorization: Bearer … 发送。
STABLEOPS_ORG_SLUG否demo作为 x-stableops-org 发送。
STABLEOPS_ENVIRONMENT否sandboxsandbox 或 live。
STABLEOPS_AGENT_SESSION_ID是—把这个 MCP 进程绑到一个可审计的 session。

请先调用 POST /v1/agent/sessions 创建 session id，这样 dashboard 才能看到它的动作并随时吊销。

接入各 MCP host

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

Claude Desktop

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

{
  "mcpServers": {
    "stableops": {
      "command": "npx",
      "args": ["-y", "@stableops/mcp-server"],
      "env": {
        "STABLEOPS_API_URL": "https://api.stableops.dev",
        "STABLEOPS_API_KEY": "sk_sandbox_xxx",
        "STABLEOPS_ORG_SLUG": "demo",
        "STABLEOPS_ENVIRONMENT": "sandbox",
        "STABLEOPS_AGENT_SESSION_ID": "agent_sess_01"
      }
    }
  }
}

Claude Code (CLI)

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

claude mcp add stableops -s user -- npx -y @stableops/mcp-server \
  -e STABLEOPS_API_URL=https://api.stableops.dev \
  -e STABLEOPS_API_KEY=sk_sandbox_xxx \
  -e STABLEOPS_ORG_SLUG=demo \
  -e STABLEOPS_ENVIRONMENT=sandbox \
  -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 = "npx"
args = ["-y", "@stableops/mcp-server"]
env = { STABLEOPS_API_URL = "https://api.stableops.dev", STABLEOPS_API_KEY = "sk_sandbox_xxx", STABLEOPS_ORG_SLUG = "demo", STABLEOPS_ENVIRONMENT = "sandbox", 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": ["npx", "-y", "@stableops/mcp-server"],
      "environment": {
        "STABLEOPS_API_URL": "https://api.stableops.dev",
        "STABLEOPS_API_KEY": "sk_sandbox_xxx",
        "STABLEOPS_ORG_SLUG": "demo",
        "STABLEOPS_ENVIRONMENT": "sandbox",
        "STABLEOPS_AGENT_SESSION_ID": "agent_sess_01"
      }
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "stableops": {
      "command": "npx",
      "args": ["-y", "@stableops/mcp-server"],
      "env": {
        "STABLEOPS_API_URL": "https://api.stableops.dev",
        "STABLEOPS_API_KEY": "sk_sandbox_xxx",
        "STABLEOPS_ORG_SLUG": "demo",
        "STABLEOPS_ENVIRONMENT": "sandbox",
        "STABLEOPS_AGENT_SESSION_ID": "agent_sess_01"
      }
    }
  }
}

VS Code（GitHub Copilot Agent）

.vscode/mcp.json：

{
  "servers": {
    "stableops": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@stableops/mcp-server"],
      "env": {
        "STABLEOPS_API_URL": "https://api.stableops.dev",
        "STABLEOPS_API_KEY": "sk_sandbox_xxx",
        "STABLEOPS_ORG_SLUG": "demo",
        "STABLEOPS_ENVIRONMENT": "sandbox",
        "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!,
  baseUrl: process.env.STABLEOPS_API_URL,
  organizationSlug: 'demo',
  environment: 'sandbox',
  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 支付单；任何资金外发都需要在 dashboard 上由人工操作。
  • Agent 不能绕过策略。即使是只读工具也会过 /v1/agent/actions，所以一旦吊销 session，之后的调用全部立即失败。
  • 即便被 prompt injection 诱导调用 create_payment_order，触及白名单之外的范围最多 落到 pending_approval —— 最坏的结果是 dashboard 上多一条待审记录，而不是真发出付款。

下一步

Webhook 验签

跨运行时验证 Webhook 签名。

Policies

用策略引擎约束 Agent 与后台动作。

本页内容

工具集启动服务器接入各 MCP hostClaude DesktopClaude Code (CLI)Codex CLIopencodeCursorVS Code（GitHub Copilot Agent）其它 host在自有 host 内嵌入一次工具调用的生命周期安全特性下一步