MCP tools

​

Payments (6)

Managed wallets use request, then execute. External wallets use approve, your own transfer, then confirm. See wallet custody.

​

pay

Request and execute a payment in one step. Combines request_payment and execute_payment. Fails if the payment is denied or requires manual approval. Replaying a completed payment returns status: completed and alreadyExecuted: true without calling execution again. Use check_payment_status with the returned requestId to retrieve its existing transaction.

​

request_payment

Authorization returns APPROVED, DENIED, REQUIRES_APPROVAL, PROCESSING, or COMPLETED. Execute only an approved request. Use check_payment_status for a request that is awaiting review, processing, or already completed. Parameters: Same as pay. Returns: requestId, status, amount, currency, recipient, reasons, and, when approved, expiresAt and actionUrl.

​

execute_payment

Execute a previously approved payment request. Execution is not automatically retried. After a timeout or ambiguous failure, call check_payment_status with the same requestId before deciding whether another execution attempt is safe. If an approver already executed the payment by approving it in Conto, execute_payment returns the existing receipt with alreadyExecuted: true and sends nothing. Before approval it fails with APPROVAL_PENDING. A payment declined at execution fails with POLICY_DENIED_AT_EXECUTION and must not be retried. POLICY_REAPPROVAL_REQUIRED means the payment needs a new request and approval. check_payment_status returns the reasons.

​

approve_external_payment

Request approval for a payment from an external (agent-held) wallet.

​

confirm_external_payment

Confirm an externally executed payment was completed onchain. approvalId is the payment request ID, so pass it as requestId. approvalRequestId, returned when the payment needs review, is a different ID for the human review. Do not pass it here. Repeated confirmation does not duplicate spend but can return 409 ALREADY_CONFIRMED. Compare the returned hash with your saved transfer and reconcile through the status URL before taking further action.

---

​

Checkout checkpoints (5)

For a checkout the agent completes itself. Call checkout_checkpoint_begin right before opening Link or another payment method, and checkout_checkpoint_confirm right before submitting the payment. See checkout checkpoints.

​

checkout_checkpoint_begin

Open the payment method only if the result’s stage is APPROVED. If the call fails, stop the checkout. If the stage is AWAITING_APPROVAL, the agent’s rules need the owner to approve the purchase. The result’s message tells the agent not to open the payment method. Call checkout_checkpoint_status every few seconds until the stage is APPROVED, then continue. Stop if it becomes DENIED, CANCELLED, or EXPIRED. The spend stays held until then or until the agent cancels.

​

checkout_checkpoint_confirm

Submit the payment only if the result’s stage is CONFIRMED. Takes checkpointId, the final amountMinor, and optional totals, pageUrl, and linkRequestId. If the final total differs from the approved one, the tool replaces the approval with one for the final total and returns it. Use its id from then on. With a Stripe Link card, pass its linkRequestId. A different total then returns LINK_CARD_TOTAL_CHANGED instead, because the card covers only the approved total. The new checkpoint can need the owner’s approval. If the result’s stage is AWAITING_APPROVAL, do not pay. Poll checkout_checkpoint_status until the stage is APPROVED, then call checkout_checkpoint_confirm again.

​

checkout_checkpoint_report_outcome

Takes checkpointId, outcome (PAID, NOT_PAID, or UNKNOWN), an optional order or receipt reference, and, with a Stripe Link card, its linkRequestId. PAID keeps the amount counted toward the agent’s limits, NOT_PAID releases it, and UNKNOWN keeps it counted until you report again. Report an outcome only after checkout_checkpoint_confirm returns CONFIRMED.

---

​

Stripe Link cards

The MCP server does not issue Stripe Link cards. A tool result goes into the model’s context and often into the MCP host’s logs, so a card number and CVC must never be in one. The earlier checkout_get_link_card tool is not listed, and a direct call returns LINK_CARD_TOOL_DISABLED without contacting Conto or Link. Get Link cards with conto.checkout.getLinkCard() in code the model does not see. Pass the agent only the linkRequestId and masked details such as last4. The checkpoint tools take that linkRequestId: checkout_checkpoint_confirm and checkout_checkpoint_report_outcome send it to Conto as the payment reference, and checkout_checkpoint_cancel cancels the Link request too when CONTO_LINK_WALLET is link-cli and link-cli is on the PATH. For an approved or waiting checkpoint it cancels the Link request first. If Link cannot cancel it and does not report it closed, the tool returns LINK_CARD_NOT_CANCELLED with holdReleased: false and keeps the spend held. If a linkRequestId is supplied but the Link wallet is unavailable, the tool also keeps the hold and returns this error. Restore Link access and call it again with the same IDs to retry. See Stripe Link cards for agents.

---

​

Guarded browser checkout (optional)

These four tools appear only when you configure a trusted browser runtime (see the configuration reference).

​

guarded_browser_checkout

The tool performs one payment-sensitive browser action through a trusted runtime that owns the page. The agent remains responsible for merchant discovery, shopping, cart construction, checkout preparation, and the purchase proposal. The runtime binds the exact target the agent supplies, asks Conto for policy authorization, claims it once, re-verifies the target, and performs the click. The MCP result never contains a raw locator, payment credential, or reusable authorization. Required inputs are a stable idempotencyKey, browserSessionId, a runtime-supported locator, actionKind, checkoutMethod, the expected amount in USD cents (amountMinor), purpose, counterparty, cart, and providerPresentation. Supported checkout methods are CARD, SHOP_PAY, and PAYPAL. For a Link checkout, use checkout checkpoints. The returned requiredControlBoundary identifies checkout preparation as AGENT, the payment action as CONTO_RUNTIME, and the requirement for an exclusive payment path. It states the integration contract. It does not attest that the agent host removed bypass tools. The browser outcome reports dispatch evidence with settlement set to UNVERIFIED. Reconcile settlement through merchant or provider evidence. For enforceable policy controls, the agent host must not also expose an unrestricted payment click or submit tool.

​

observe_browser_session

Read-only. Takes one browserSessionId and returns only the page’s HTTPS origin, a bounded title, and up to 50 visible link and button descriptors. It withholds page text, DOM, form values, screenshots, cookies, storage, and URL paths and queries. Returned positional locators are inert target references for a later guarded_browser_checkout. The tool cannot navigate, click, type, submit, or run JavaScript.

​

create_browser_session and release_browser_session

create_browser_session takes no parameters and returns only an opaque session ID, status, and expiry. Creation is not idempotent. Do not retry it automatically after a timeout or network error, because the earlier request may have succeeded. release_browser_session takes the exact browserSessionId and revokes Conto ownership before the runtime closes the session. Call it after checkout or abandonment. Reconcile an ambiguous release instead of repeating it. An agent browser host that already owns and registers its session with the runtime does not need these two tools.

---

​

Wallets and limits (3)

​

get_wallet

---

​

Budget requests (2)

​

request_budget

Request a spending budget for payments. Submits a request for human approval. Only one active budget request per agent at a time. Applies to all payment types (standard, x402, MPP).

​

get_budget_request

Check status and remaining balance of your budget requests. Use it to poll for approval after submitting a request, and to monitor remaining budget during spending.

---

​

Transactions (3)

list_transactions returns paginated transaction records with related resource IDs, lifecycle timestamps, authorization decisions, and network receipt data. get_transaction adds source-wallet and recipient identities plus linked alerts, so an agent can explain and reconcile a payment. retry_transaction requires transactionId and both transactions:write and payments:execute scopes. It creates or resumes one retry payment after a definitive failure, preserving the original receipt and rechecking execution controls. The response includes the retry request ID, transaction ID when available, current status, and statusUrl. Inspect that URL after an ambiguous client result. If the outcome is unknown or a reconciliation alert is open, a person must resolve it in the dashboard before a retry runs.

​

list_transactions

---

​

Connected cards (1)

Connected cards (Builder and Enterprise plans) are cards you enroll in Conto and delegate to this agent. connected_card_list is read-only (transactions:read), takes no parameters, and returns masked cards only. Each card exposes last4, brand, funding type, spending limits, and its active mandates. No card number, security value, or provider token is ever returned. No MCP tool draws a connected-card credential, because tool results land in the model transcript and host logs. Draw credentials with the SDK (conto.connectedCards.draw).

---

​

Conto Commerce (7)

purchase_start needs buyerId, url, maxCostMinor (US cents) and an idempotencyKey you reuse when retrying. Pass paymentMethodId and delegationId together to choose the card. Without them, the buyer’s one authorization for that kind of store is used. For groceries at an Instacart store, pass groceryList instead of items. It returns at once and the purchase continues in the background. Pass after to purchase_status to also get the events since that version. The buyer reviews every purchase and verifies their card on a Conto page, so purchase_respond refuses review, approval and card verification. Share requiredAction.url with the buyer instead. No purchase tool returns card details or a store browser. See the Conto Commerce API. A repeat order is set up by the buyer while approving a purchase. Start each order with recurring_purchase_start_cycle and a cycleKey you reuse when retrying, then follow the returned purchase with purchase_status. The buyer gets a heads-up before each order and can skip it.

---

​

x402 protocol (5)

Request and response fields are in the x402 API reference. The notes below cover behavior an agent needs to handle. Pre-authorize. x402_pre_authorize requires amount, recipientAddress, and resourceUrl. serviceDomain is derived from resourceUrl. An approved decision returns grantId, grantSignature, and grantExpiresAt, and reserves the amount against the agent’s spend limits for 10 minutes. Calling again with the same paymentId returns the same live grant. A declined or review-required decision returns fixed reasons and reasonCodes, such as SPENDING_LIMIT or RECIPIENT_NOT_ALLOWED, without rule values. Pay from a managed wallet. x402_pay requires payments:execute and takes the pre-authorize fields plus paymentRequirements, the accepted entry from the 402 challenge. recipientAddress must equal paymentRequirements.payTo, and the challenge scheme must be exact. Conto evaluates the payment exactly like x402_pre_authorize. Only an approved payment is signed: Conto signs an EIP-3009 authorization for that payee, amount, and USDC contract with the managed EVM wallet, so a declined payment cannot be paid from it. The result adds paymentHeaderName and xPaymentHeader. Retry the resource request with that header, then call x402_record with the grant and the settlement txHash. Each grant is signed once, and a second call for the same payment returns GRANT_ALREADY_SIGNED. Wallets Conto cannot sign for return MANAGED_SIGNING_UNAVAILABLE. For those, call x402_pre_authorize and sign with your own wallet. Record. x402_record requires amount, recipientAddress, resourceUrl, txHash, and paymentId. Reuse the same paymentId when retrying. Send batchItems to record several micropayments at once. Provide payerAddress and network together on both the pre-authorize and record calls. They are required when the agent has more than one active wallet. Pass grantId and grantSignature from the approved x402_pre_authorize or x402_pay result on every record. A record without a valid, unexpired grant is accepted as a policy bypass: the result includes policyBypass: true, the payment is flagged, and the account owner receives a critical alert. Organizations can also have the agent frozen automatically, and agentFrozen reports whether it was. Budget and services. Pass an optional sessionId to x402_get_budget to include spend for that session alongside the daily, weekly, and monthly totals. x402_list_services takes period (24h, 7d, 30d, or 90d, default 7d) and limit (default 50, max 100).

---

​

MPP protocol (4)

Request and response fields are in the MPP API reference. Pre-authorize. mpp_pre_authorize requires amount, recipientAddress, and resourceUrl. Set intent to charge or session. A session intent also requires sessionId, and depositAmount sets the session deposit. An approved decision returns grantId, grantSignature, and grantExpiresAt, and reserves the amount until grantExpiresAt. A charge grant covers one payment of that exact amount and expires after 10 minutes. A session grant is a ceiling that several mpp_record calls may draw down. It lasts for the session’s maximum duration: the shortest MPP_MAX_SESSION_DURATION that applies, or 24 hours by default. Calling again with the same challengeId or credentialId returns the same live grant. A declined or review-required decision returns fixed reasons and reasonCodes, as x402_pre_authorize does. Record. mpp_record requires amount, recipientAddress, resourceUrl, and credentialId. Reuse the same credentialId when retrying. Send closeSession: true on a session’s final record (mcp-server 0.5.3 or later). If the session charged nothing, send amount: 0 with closeSession: true and the session grant. The result has sessionClosed: true. txHash and paymentReceipt are optional. Recording rejects an unsuccessful receipt, a receipt bound to a different challenge, or a settled amount that does not match amount. Receipt parsing is only a consistency check because the caller supplies the payload, so a receipt-only record stays pending. An onchain transaction is marked confirmed only after its sender, recipient, amount, and currency match the record. Without a valid, unexpired grant, the record is accepted as a policy bypass, as with x402_record. Budget and services. mpp_get_budget takes an optional sessionId, and mpp_list_services takes period and limit, as the x402 tools do.

---

​

Agent-to-agent (6)

​

a2a_send_request

​

a2a_list_requests

​

a2a_respond

Approval succeeds only when the paying agent’s policies allow the payment. If policy requires human approval, the request stays pending with code: "HUMAN_APPROVAL_REQUIRED" until a person in the paying organization approves it while signed in to Conto.

---

​

Trust and counterparties (4)

​

list_counterparties

​

create_counterparty

---

​

Alerts and approvals (4)

​

list_alerts

​

get_alert

​

respond_to_alert

​

get_approval_requests

Lists payment requests waiting for human approval and A2A requests. The agent cannot decide its own payment requests. A person approves or rejects them from the email link or the dashboard. Answer incoming A2A requests with a2a_respond.

---

​

Analytics and info (7)

get_analytics takes an optional period: day, week, month (default), or year.

​

get_setup

Returns the agent, linked wallets, effective policies, scopes, and the versioned setup diagnostics described in setup diagnostics. The tool’s output schema describes them. Call it first to learn the environment, whether the key can request and execute payments, and which remaining issues belong to the agent or to an owner. For a key Conto recognizes but will not serve, such as a paused or frozen agent, an expired or revoked key, or a key without agents:read, get_setup returns an error result that still carries the diagnostics. Relay the owner actions it lists instead of retrying.

​

request_policy_exception

Use this when a payment is blocked and the agent needs a counterparty, spending-limit, time-window, category, or custom policy change reviewed. The API key must include the policies:exceptions scope. The response includes the request reference, normalized type and priority, current review status, timestamps, and a dashboard review URL.

​

list_policy_exceptions

List policy change requests with their review statuses and pagination. The API key must include the policies:exceptions scope.

​

get_all

get_all is retained for compatibility with existing MCP integrations. New integrations should use get_setup and the dedicated list tools. Use the optional include parameter to request only the sections you need. A section is returned only when the API key has its corresponding read scope. omittedSections identifies sections that could not be returned and the scope each one requires.

---

​

Audit and rate limits (2)

​

get_audit_logs

​

Simulated payment receipts

Sandbox payments are simulated. Every receipt has transactionId and settlementMode, and txHash is present only for an onchain transfer. check_payment_status reports settlementMode as live, test, or unknown. Never report a test receipt as an onchain transfer.