# StableOps Agent Payments MCP Server

[中文文档](./README.zh-CN.md)

A stdio Model Context Protocol (MCP) server that lets agents configure and run StableOps Agent Payments while private keys, seed phrases, KMS credentials, and approval authority remain user-controlled.

## Install and run

Node.js 20 or later is required.

Provide only the management key during setup:

```bash
STABLEOPS_API_KEY=sk_sandbox_... \
STABLEOPS_AP_ENABLE_MANAGEMENT_WRITES=true \
STABLEOPS_AGENT_KEY_OUTPUT_FILE=/protected/absolute/path/stableops-agent-key \
npx -y -p @stableops/agent-payments-mcp-server@0.2.0 stableops-agent-payments-mcp
```

Management mode is read-only by default. Mutating tools are registered only with `STABLEOPS_AP_ENABLE_MANAGEMENT_WRITES=true`; the management process never exposes open-world discovery or payment execution. The one-time Agent Key secret is never returned to the model. The server reserves the `0600` destination before issuance and automatically revokes a newly issued key if storage fails.

The wallet-pairing tool returns only the exact message the user must sign. No tool accepts a private key, seed phrase, or KMS credential. The user signs in their own wallet and returns only the signature.

For daily runtime use, remove the management key and use a restricted Agent Key plus the user-operated signer sidecar:

```bash
STABLEOPS_AGENT_KEY=ak_sandbox_... \
STABLEOPS_SIDECAR_URL=http://127.0.0.1:8789 \
STABLEOPS_SIDECAR_TOKEN=... \
npx -y -p @stableops/agent-payments-mcp-server@0.2.0 stableops-agent-payments-mcp
```

Management and runtime modes are mutually exclusive. The server refuses to start when both `STABLEOPS_API_KEY` and `STABLEOPS_AGENT_KEY` are set. Runtime mode only exposes discovery, budget, preview, controlled purchase, and payment-reconciliation tools; it cannot change policy or approve its own payment.

## Security model

- The server never accepts or stores wallet private keys, seed phrases, or KMS credentials.
- The user must sign wallet-ownership proofs outside the server.
- Runtime payment can only call the user-operated constrained signer sidecar, never an arbitrary signing endpoint.
- Unknown origins, unknown recipients, and above-threshold payments require human approval in StableOps.
- Every new purchase requires a stable `idempotency_key`; uncertain settlement must reconcile the original intent.
- Every purchase must use a `preview_token` bound to the exact URL, maximum quote, and audit context; the purchase tool accepts no replacement URL.
- Preview tokens are process-local. After an MCP restart, preview the original exact URL again and resume with the new token; the API verifies the full URL hash stored on the intent.
- Responses over 256 KiB are available as short-lived MCP resources; all inline summaries are marked as untrusted external content.

## Documentation

See the complete guide at https://stableops.dev/en/docs/agent-payments/quickstart

## License

Apache-2.0