MCP Server

@stableops/mcp-server is a stdio MCP server that wraps the StableOps SDK as a fixed set of tools. AI agents (Claude Desktop, Cursor, any MCP-compatible host) can call these tools only. They cannot talk to the API directly, and every call is gated by the workspace's agent policy.

What the toolkit exposes

MCP tools are grouped by resource family. Every tool goes through /v1/agent/actions first. Read tools are usually auto-allowed; write tools are constrained by the allow-list and approval switch.

Payment Orders

Tool	Kind	Description
`list_payment_orders`	read	List payment orders.
`get_order`	read	Look up one payment order by id.
`create_payment_order`	write	Create a payment order.
`cancel_payment_order`	write	Cancel a payment order.

Addresses

Tool	Kind	Description
`get_address_pools`	read	Read address pool configuration.
`list_addresses`	read	List available or allocated addresses.
`import_addresses`	write	Import addresses in bulk.
`update_address`	write	Update address status or metadata.
`remove_address`	write	Remove an address.

Webhooks

Tool	Kind	Description
`list_webhook_endpoints`	read	List webhook endpoints.
`create_webhook_endpoint`	write	Create a webhook endpoint.
`update_webhook_endpoint`	write	Update a webhook endpoint.
`rotate_webhook_secret`	write	Rotate an endpoint signing secret.
`list_webhook_deliveries`	read	Read recent webhook deliveries.
`replay_webhook_delivery`	write	Replay one delivery.
`replay_webhook_dead_letters`	write	Replay dead-lettered deliveries.

Checkout Sessions

Tool	Kind	Description
`create_checkout_session`	write	Create a hosted checkout session.

Agents

The Agents group only exposes read tools and request_action_approval. MCP does not expose upsert_agent_policy, approve_agent_action, reject_agent_action, or revoke_agent_session, so an agent cannot modify or approve its own guardrails.

Tool	Kind	Description
`list_agent_sessions`	read	List agent sessions.
`get_agent_policy`	read	Read the current policy.
`list_agent_actions`	read	List agent action audit records.
`request_action_approval`	write	Register a custom approval request; it does not execute a StableOps API call.

Merchant Subscriptions

Tool	Kind	Description
`list_merchant_plans`	read	List subscription plans.
`create_merchant_plan`	write	Create a subscription plan.
`update_merchant_plan`	write	Update a subscription plan.
`delete_merchant_plan`	write	Delete a subscription plan.
`create_merchant_subscription`	write	Create a merchant subscription.
`list_merchant_subscriptions`	read	List merchant subscriptions.
`get_merchant_subscription`	read	Read subscription details.
`get_merchant_subscription_by_user`	read	Find a subscription by user.
`change_merchant_subscription_plan`	write	Change a subscription plan.
`cancel_merchant_subscription`	write	Cancel a subscription.
`resume_merchant_subscription`	write	Resume a subscription.
`list_merchant_invoices`	read	List subscription invoices.
`get_merchant_invoice`	read	Read invoice details.
`pay_merchant_invoice`	write	Pay a subscription invoice.
`get_merchant_invoice_payment_status`	read	Read invoice payment status.
`get_merchant_subscription_settings`	read	Read subscription settings.
`update_merchant_subscription_settings`	write	Update subscription settings.
`create_merchant_portal_session`	write	Create a portal session.
`revoke_merchant_portal_session`	write	Revoke a portal session.

Read tools default to auto_allowed. Write tools always go through POST /v1/agent/actions first; if the policy says require_approval=true, the call returns pending_approval and the agent must wait for a human to approve in the dashboard.

Installation and configuration

First install @stableops/mcp-server globally so the stableops-mcp command is available on your machine:

pnpm add -g @stableops/mcp-server

Installation only makes the stableops-mcp command available on your machine. For normal use, you do not need to start it manually in a separate terminal. MCP hosts such as Claude Desktop, Cursor, Codex CLI, and OpenCode start and manage the stdio child process automatically from their configuration.

Provide the following environment variables in the MCP host configuration:

Variable	Required	Default	Notes
`STABLEOPS_API_KEY`	yes	—	Sent as `Authorization: Bearer …`. The environment (sandbox / live) is determined by the key itself.
`STABLEOPS_AGENT_SESSION_ID`	yes	—	Bind this MCP process to one audited session.
`STABLEOPS_API_URL`	no	`https://api.stableops.dev`	Override the API base URL (self-hosted or testing setups).

Getting a Session ID

The recommended flow is to create it in the Dashboard:

Open Dashboard → Agents and select the environment used by the MCP API key (Sandbox or Live).
Click Create session in the Sessions section. Add an optional label and expiry.
Copy the returned Session ID into STABLEOPS_AGENT_SESSION_ID in your MCP host configuration.

The Session ID must belong to the same organization and environment as STABLEOPS_API_KEY. Otherwise every MCP tool will return agent session not found.

For automated deployments, call POST /v1/agent/sessions and use the id from the response:

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"}'

Client configuration examples

Every host wants the same three things: the stableops-mcp command, no arguments, and the env block above. Only the configuration path and field names differ.

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)

One-shot CLI registration. Scope to the current project by default, drop -s user to share globally:

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

Or hand-edit ~/.claude.json under mcpServers with the same JSON shape as Claude Desktop.

Codex CLI

~/.codex/config.toml. Codex reads TOML, not 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 (or opencode.json at the project root):

{
  "$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 (global) or .cursor/mcp.json (per project):

{
  "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"
      }
    }
  }
}

Other hosts

Cline, Continue, Gemini CLI, Windsurf, Zed and any other MCP-aware client take the same shape: a stdio command, optional args, and the env block. Substitute their config file path and key naming.

Embed in your own host

If you build a custom Node host you can create the server directly without shelling out to the binary:

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())

Lifecycle of a tool call

agent ─▶ tool call ─▶ POST /v1/agent/actions
                       │
                       ├── decision = auto_allowed   ─▶ SDK call ─▶ POST /actions/:id/executed
                       └── decision = pending_approval ─▶ blocked response
                                                          │
                                                          (human approves in dashboard,
                                                           agent re-attempts the tool call)

Every tool returns either a structured result (typed against the tool's outputSchema) or an isError envelope. The structured shape mirrors what the SDK returns from the underlying resource call: camelCase keys, the same enum values you see on /v1/payment-orders.

Security boundaries

The agent cannot initiate on-chain transactions. StableOps itself holds no private keys and cannot sign or broadcast transactions. Calling create_payment_order only creates a payment request; the actual on-chain transfer is made by the payer. Statuses like confirmed come from chain scanning and are not controlled by any API.
The agent cannot bypass the policy. Even read tools go through /v1/agent/actions, so revoking the session blocks every subsequent call immediately.
Write tools are gated by the allow-list and require_approval flag. Prompt injection that hits a tool outside the allow-list or requiring approval falls through to pending_approval — the worst case is a queued action that needs human approval in the dashboard to take effect.

Agent policies: set allowed tools and approval rules.
API Reference → Create payment order: the underlying contract every write MCP tool talks to.