StableOps
Agent

MCP Server

安裝並設定 StableOps MCP Server，以受限憑據向 AI 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，需人工在控制台批准後才會生效。

下一步

這篇文件怎麼樣？

最後更新

訂閱

使用 StableOps 建立穩定幣訂閱方案、為商戶使用者開通和管理訂閱、自動生成帳單，並讓終端使用者透過託管結帳頁或自有錢包流程付款；再根據已驗證的訂閱事件更新服務狀態。完整覆蓋方案變更、取消、恢復、帳單支付和付款狀態查詢，幫助業務可靠維護訂閱生命週期。

Agent 策略

瞭解如何為 StableOps Agent 設定工具白名單、金額限制與人工審批閘門，使每個會話只能執行明確授權的查詢和低風險操作；文件同時說明組織與環境作用域、策略更新方式、敏感動作審批，以及拒絕或過期後的安全行為。

本頁內容

工具集Payment OrdersAddressesWebhooksCheckout SessionsAgentsMerchant Subscriptions安裝與設定取得 Session ID用戶端設定示例Claude DesktopClaude Code (CLI)Codex CLIopencodeCursorVS Code（GitHub Copilot Agent）其它 host在自有 host 內嵌入一次工具呼叫的生命週期安全邊界下一步