MCP API

The Stablecoin Harness MCP server exposes the merchant account as a flat catalog of tools, named by resource. This page is the reference for each tool. For installation and configuration, see Features → MCP Server.

On failure a tool throws an error whose message is prefixed with a machine-readable code that tells the agent what to do next: LOGIN_REQUIRED, RE_AUTH_REQUIRED, OTP_INVALID, OTP_EXPIRED, or API_KEY_REQUIRED.

Auth

`auth_send_otp`

Send an email OTP to begin login.

input:  { email: string }
output: { sent: true }   // OTP emailed to the user

`auth_verify_otp`

Complete the OTP flow: connect the in-app wallet, sign the SIWE payload, mint a JWT, and optionally bootstrap an API key + session key.

input:  { email: string; code: string }
output: { authenticated: true; smartAccountAddress: string }

`auth_status`

Inspect cached credentials and their expiry. Read-only.

`auth_logout`

Wipe local credentials (does not revoke server-side).

API keys

`api_key_create`

POST /v1/merchants/me/api-keys. Raw key returned once, then stored encrypted.

input:  { label?: string }
output: { id: string; label: string; rawKey: string }

`api_keys_list` / `api_keys_revoke`

List keys (hash + prefix only) / revoke by id. GET / DELETE /v1/merchants/me/api-keys[/:id].

Session keys

`session_key_create`

Generate a local EOA and add it as a session key on the smart account.

input:  { approvedTargets?: string[]; validDays?: number }
output: { sessionKeyAddress: string; validUntil: number }

Merchant

`merchant_get` / `merchant_update`

Read / update the merchant profile. GET / PATCH /v1/merchants/me.

Sessions

`sessions_create_dashboard`

Create a payment session under the merchant JWT (POST /v1/merchants/me/sessions).

input:  { amount: string; merchantName?: string; lineItems?: LineItem[];
          paymentOptionSymbols?: ("USDC"|"USDT"|"USDe")[]; expiresInSec?: number;
          successUrl?: string; sandboxMode?: boolean }
output: { id: string; paymentUrl: string; status: string; expiresAt: string; createdAt: string }

`sessions_get` / `sessions_list`

Fetch one session / list recent sessions. GET /v1/merchants/me/sessions[/:id].

Paymaster

`paymaster_clients_list` / `_create` / `_update` / `_revoke`

Manage publishable client keys (pmc_*) — /v1/paymaster/clients.

`paymaster_allowlist_list` / `_add` / `_remove`

Manage the (chainId, contractAddress) allowlist — /v1/paymaster/allowlist.

`paymaster_usage_get`

List sponsorship usage records — /v1/paymaster/usage.

Webhooks

`webhooks_create` / `_list` / `_delete` / `_rotate_secret`

Manage webhook endpoints over the server-key surface /v1/webhooks (uses the cached sk_* key). webhooks_create returns the signing secret (whsec_*) once.

`webhooks_deliveries`

List delivery history for an endpoint — GET /v1/merchants/me/webhooks/:id/deliveries (uses the JWT).

Credentials per tool

Tool group	Credential
`auth_*`	none / OTP code
`api_key_create`, `api_keys_`, `session_key_create`, `merchant_`	JWT
`sessions_create_dashboard`, `sessions_*`	JWT
`paymaster_*`	JWT
`webhooks_create` / `_list` / `_delete` / `_rotate_secret`	API key (`sk_*`)
`webhooks_deliveries`	JWT

The MCP holds the merchant’s full authority — there is no per-tool privilege tier on the API side. Scoping is a client-side concern (per-tool confirmation prompts in your agent).

MCP API

Auth

auth_send_otp

auth_verify_otp

auth_status

auth_logout

API keys

api_key_create

api_keys_list / api_keys_revoke