Quickstart

Install the Agent Payments MCP server and signer CLI so an agent can configure the payment rail and pay within policy while the user pairs wallets and starts signing from a trusted terminal.

Install

Node.js 20 or later is required. Install the MCP server and signer CLI globally:

pnpm add -g @stableops/agent-payments-mcp-server @stableops/agent-payments-signer

The MCP host starts stableops-agent-payments-mcp from its configuration. The user runs stableops-agent-payments-signer in a trusted terminal.

The security boundary remains explicit:

Prerequisites

This quickstart uses Base Sepolia, the recommended network for a first Sandbox payment. Complete it before configuring another network. When a paid service requires another network, confirm that its payment requirement matches the network and USDC in the supported scope, then start with a small payment that requires human approval.

• A StableOps organization and a sandbox Agent Payments management API key.
• A dedicated Base Sepolia payment wallet whose private key you control. Create a test-only account in an EVM wallet that supports Base Sepolia, keep only test assets in it, and do not reuse a wallet that holds real assets. The sandbox network is eip155:84532. Official test USDC is 0x036CbD53842c5426634e7929541eC2318f3dCF7e.
• Test USDC in that wallet. The facilitator submits the current EIP-3009 transaction, so the payer does not need test ETH for this flow.

Amounts and budgets use atomic-unit strings. USDC has six decimals, so 1000000 is 1 USDC. Sandbox ceilings are 1 USDC per payment, 10 USDC per Agent per day, and 100 USDC per organization per day.

1. Give the management MCP to your agent

The configuration below belongs in the MCP host configuration file on the machine running the agent. Do not put it in the project's .env file or paste it into a terminal as a standalone command. Common locations include:

• Claude Desktop on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json for global configuration or .cursor/mcp.json for project configuration
• Codex CLI: ~/.codex/config.toml, using the TOML example below

Other MCP hosts need the same command and environment variables, although their file locations and field names may differ. Restart the MCP host after editing the configuration so it launches a new server process.

Prepare configuration values

On macOS or Linux, prepare a parent directory accessible only to the current user. These commands do not create the agent-key file:

mkdir -p "$HOME/.config/stableops"
chmod 700 "$HOME/.config/stableops"

Expand $HOME to the real absolute path in the MCP configuration, for example /Users/alice/.config/stableops/agent-key.

JSON configuration example

For an MCP host that uses JSON, add:

{
  "mcpServers": {
    "stableops-agent-payments": {
      "command": "stableops-agent-payments-mcp",
      "env": {
        "STABLEOPS_API_KEY": "sk_sandbox_replace_with_management_key",
        "STABLEOPS_AP_ENABLE_MANAGEMENT_WRITES": "true",
        "STABLEOPS_AGENT_KEY_OUTPUT_FILE": "/protected/absolute/path/stableops-agent-key"
      }
    }
  }
}

Replace all three example values according to the guidance above. The stableops-agent-payments key under mcpServers is only a local display name and may be changed. Keep command set to the installed stableops-agent-payments-mcp executable.

Codex CLI configuration example

Codex CLI uses TOML. Add the equivalent configuration to ~/.codex/config.toml:

[mcp_servers.stableops-agent-payments]
command = "stableops-agent-payments-mcp"
env = { STABLEOPS_API_KEY = "sk_sandbox_replace_with_management_key", STABLEOPS_AP_ENABLE_MANAGEMENT_WRITES = "true", STABLEOPS_AGENT_KEY_OUTPUT_FILE = "/Users/alice/.config/stableops/agent-key" }

Management mode is read-only by default. Enable management writes only for a trusted initial setup session, then remove the switch and management API key.

Console: Create and save the organization-level sk_sandbox_... management API key. Keep this key for the initial setup session only.

MCP response: The MCP server returns the complete wallet-pairing challenge after the Agent calls stableops_ap_create_wallet_pairing_challenge.

Protected output file: After wallet registration, policy activation, and an explicit call to stableops_ap_issue_agent_key, the MCP server writes the one-time ak_sandbox_... Agent Key to STABLEOPS_AGENT_KEY_OUTPUT_FILE.

After connecting the MCP server, give the Agent this configuration objective:

Use the StableOps Agent Payments MCP to configure sandbox payments for research-agent:
- Network: eip155:84532
- Wallet address: <replace with the public address of your Base Sepolia test payment wallet>
- Signer: LOCAL_TEST with key id local:<the same wallet address in lowercase>
- Start with no automatic-payment allowlist and an automatic threshold of 0
- Per-payment limit: 1000000. Agent daily limit: 10000000.
- Do not change the organization budget

List existing Agents first to avoid duplicates. After creating the wallet-pairing challenge,
stop and show me the complete message in a plain-text code block for review and signing. Keep
the challenge to exactly seven lines with no indentation or inserted line breaks. Never ask for a private key or
seed phrase. Once I return the signature, register and bind the wallet, create and simulate the
policy, activate it, and finally call `stableops_ap_issue_agent_key` to issue the runtime Agent Key.

The wallet address is the public address that will spend test USDC, not an address supplied by StableOps or the merchant. It must meet these requirements:

1. You can sign the later pairing challenge with that wallet account to prove control.
2. The test private key used by LocalTestSigner derives the same address. Otherwise payment signing is rejected.
3. The address holds enough Base Sepolia test USDC. It does not need test ETH for the current flow.

Use a dedicated account that holds only a small amount of test assets. local:<lowercase-wallet-address> is a non-secret identifier for the local signing key, not a private key or another wallet address.

The Agent should inspect existing resources, create and simulate the policy, then activate it separately. After wallet registration and policy activation, it must call stableops_ap_issue_agent_key with the current agent_id and a key name such as research-agent-runtime.

The Agent Key secret is never shown in the conversation. MCP creates the protected file above before requesting issuance, then writes the one-time ak_sandbox_... secret to that file. The tool result only confirms secret_stored: true and returns key metadata. If storage fails, MCP revokes the new key and never overwrites an existing file.

If stableops_ap_issue_agent_key is not in the tool list, confirm that MCP was started with STABLEOPS_AP_ENABLE_MANAGEMENT_WRITES="true" and restart the MCP host. If the tool succeeds but the file is missing, check that STABLEOPS_AGENT_KEY_OUTPUT_FILE is a new absolute path on the MCP host.

Register and bind a payment wallet

stableops_ap_create_wallet_pairing_challenge returns the challenge ID, complete message, and requires_user_action: true. The Agent must stop while the user:

1. Reviews the organization, network, wallet address, and expiry.

2. Confirms that the payment wallet private key on the signer host derives the Address in the challenge. The key must be stored in a protected file on the signer host. Never paste it into the conversation, MCP configuration, or command-line arguments.

3. In a trusted terminal, set the private-key file path:

   export STABLEOPS_EVM_PRIVATE_KEY_FILE='/protected/absolute/path/evm-private-key'

4. Copy only the complete seven-line challenge from the plain-text code block returned by the Agent. Keep the field names at the start of each line with no added indentation or inserted line breaks. Do not copy the surrounding explanation or the separate challenge ID.

5. Choose one input method for your system and run the signer only once:

   On macOS, pipe the challenge from the clipboard so standard input closes automatically:

   pbpaste | stableops-agent-payments-signer pair-wallet --signer local

   On other systems, start the interactive command:

   stableops-agent-payments-signer pair-wallet --signer local

   When the command waits for input, paste the same seven lines. Press Enter after the last line, then press Ctrl-D on the empty next line to close standard input.

6. The signer prints an EVM signature beginning with 0x to standard output. Return it to the Agent unchanged. Do not convert it to Base64 or return the private key or seed phrase.

The Agent then calls stableops_ap_register_wallet and stableops_ap_bind_wallet. The CLI validates the challenge, expiry, and key-derived address. Neither MCP nor the dashboard handles the private key.

If you use pair-wallet --challenge, the argument must be the complete challenge encoded as unpadded Base64URL. The Agent returns the raw challenge text, so piping it through standard input as shown above is the simplest option.

For the first policy, keep allowed_origins and allowed_pay_to empty and set automatic_payment_threshold_atomic to 0. Every real payment will require manual approval. After validating a service, create a new policy version containing its exact origin and recipient if automatic payment is desired.

2. Start the user-controlled signing sidecar

stableops-agent-payments-signer provides two signing commands:

• pair-wallet handles wallet registration. It validates and signs a one-time challenge, writes the signature, and exits.
• serve handles normal payments. It starts the long-running signing sidecar, validates execution grants, and signs the matching payments. Keep this process running during payment operation.

The Agent does not execute the signer CLI directly or handle wallet keys. The runtime call path is:

Agent → stableops-agent-payments-mcp → signing sidecar /v1/sign → local wallet key or AWS KMS

The MCP server obtains a short-lived execution grant from the StableOps API and sends it to the sidecar using STABLEOPS_SIDECAR_URL and STABLEOPS_SIDECAR_TOKEN. The sidecar verifies the field-bound grant before signing the matching payment and exposes no arbitrary-message signing endpoint.

Follow the Signer guide to configure and start it:

• For Sandbox testing, run stableops-agent-payments-signer serve --signer local. It defaults to 127.0.0.1:8789.
• For Live EVM wallets, run stableops-agent-payments-signer serve --signer aws-kms with a non-exportable key in AWS KMS.
• Protect the sidecar with a high-entropy token and persistent authorization storage.

This step requires the user to choose the wallet or KMS key and configure key material in a trusted environment. The Agent may check sidecar health through MCP, but must not read or custody the key.

3. Switch to the restricted runtime MCP

Initial setup uses organization-level management privileges. Daily payments use an Agent Key scoped to one Agent and environment. Runtime mode does not register management tools, and every payment still passes policy, budget, risk, approval, and signer checks.

The ak_sandbox_... secret appears in the file named by STABLEOPS_AGENT_KEY_OUTPUT_FILE only after wallet registration, policy activation, and explicit key issuance. The StableOps API provides the plaintext to MCP only once. It is never shown in the Agent conversation and cannot be recovered through a metadata query.

Read the file in a trusted terminal, move the secret into the MCP host's runtime secret configuration, confirm that the runtime configuration can read it, and then delete the temporary file. Finally, remove STABLEOPS_API_KEY and the management write switch before adding the signer URL and token:

{
  "mcpServers": {
    "stableops-agent-payments": {
      "command": "stableops-agent-payments-mcp",
      "env": {
        "STABLEOPS_AGENT_KEY": "ak_sandbox_replace_with_one_time_secret",
        "STABLEOPS_SIDECAR_URL": "http://127.0.0.1:8789",
        "STABLEOPS_SIDECAR_TOKEN": "replace_with_high_entropy_token"
      }
    }
  }
}

The three runtime values come from these locations:

• STABLEOPS_AGENT_KEY: read it from the file named by STABLEOPS_AGENT_KEY_OUTPUT_FILE during initial setup. The complete ak_sandbox_... secret belongs only to the Agent for which it was issued.
• STABLEOPS_SIDECAR_URL: use the loopback URL printed after deploying the signer sidecar in step 2. It is http://127.0.0.1:8789 with this guide's example configuration.
• STABLEOPS_SIDECAR_TOKEN: generate this high-entropy random token yourself. Configure the same value in the signer sidecar and runtime MCP. Never put it in a prompt, source code, or the repository.

On macOS or Linux, generate a 32-byte random token and store the output in a secret manager:

openssl rand -hex 32

Management mode and runtime mode are mutually exclusive. Do not leave both STABLEOPS_API_KEY and STABLEOPS_AGENT_KEY in the configuration. The MCP server refuses to start when both are present.

After restarting MCP, use runtime tools in this order:

1. Check runtime identity, budgets, supported networks, and sidecar health.
2. Discover candidates, preview the exact URL, and obtain a preview_token.
3. Purchase with that preview_token and a stable idempotency_key.
4. If approval is required, save the intent_id and resume the original payment after approval.
5. If settlement is uncertain, inspect only the original payment and never create a replacement.

Without a configured sidecar, MCP can still discover and preview but does not register purchase or resume tools. Unknown origins, unknown recipients, and above-threshold payments require console approval. The Agent cannot approve its own request.

4. Complete the first Sandbox payment

After runtime MCP and the signing sidecar are ready, continue to Buy x402 resources with Agent Payments. It walks through discovering or selecting a paid resource, reviewing the preview, purchasing, handling approval, and verifying the final state.

Next steps

• Move from a local test wallet to AWS KMS in the Signer guide.
• Subscribe to approval, settlement, and exceptional states through Webhooks.
• Before mainnet, verify networks, contracts, asset decimals, and payment methods in Supported scope.