DEVELOPER GUIDE · ANY MCP CLIENT

Generic MCP integration

A working Spendkit payment Runtime needs more than an MCP URL. Its process must acquire and refresh OAuth tokens, call MCP tools, and submit the authorized Router transaction from the Agent's bound Payment Wallet.

Start with copyable client code →

Choose the integration path

EXISTING MCP TOOL LOOPConnect the tools

If your Runtime already discovers tools and handles their results, add Spendkit's OAuth client and MCP endpoint. Keep the Payment Wallet adapter outside model context.

FIXED WORKFLOWAdd an explicit payment sequence

If your Agent has no dynamic MCP tool loop, call the tools in the documented sequence through an adapter. Adding a URL alone will not change a hard-coded payment path.

Required capabilities

OAuth 2.0 Client Credentials with short-lived token refresh and secure storage for the Client Secret.
MCP Streamable HTTP initialization, tool listing, and tool calls. Discover current tool schemas instead of guessing them.
A bound Payment Wallet client that checks the returned chain, Router, amount, recipient, and sender before submission.
Status handling that distinguishes DENY, authorization, submitted transaction, confirmed payment, and uncertain broadcast.

When an AI model chooses tools

Your Runtime calls tools/list and gives the returned names, descriptions, and input schemas to its model as callable tools. The model may suggest spendkit_preview_payment or another Spendkit tool for a user task.
Your application validates the model's arguments, sends tools/call with the Agent connection's Bearer token, and returns the structured result to the model. A tool-level DENY must stop the payment path even if the model asks to continue.
After spendkit_authorize_payment allows a payment, trusted application code compares the response with the intended amount, recipient, bound wallet, chain, and Router. A separate wallet signer submits the exact transaction. The model never receives the wallet private key or signs the transaction itself.
Your application calls spendkit_record_payment and spendkit_get_payment_status, then reports the verified outcome to the user. If submission is uncertain, reconcile the existing intent before any new action.

The local Agent Runtime example implements a model tool loop, OAuth/MCP adapter, and separate Payment Wallet sender. A fixed workflow can call the same MCP tools without exposing them to a model.

Keep roles separate

The authenticated Agent connection selects the Policy and verified Payment Wallet. Do not ask the model to supply a Policy ID or a wallet address for authorization. Spendkit Server does not receive the wallet key, send the transaction, or pay gas. The Runtime's local wallet process does those jobs after authorization.

Using a coding tool?

Codex, Claude Code, or Gemini CLI can help implement this Runtime. Their ability to connect to a generic MCP server does not by itself prove that they manage Spendkit's OAuth Client Credentials lifecycle or submit payments from the bound wallet. Use the coding-Agent guide →

Start with Runtime setup → See real HTTP/MCP requests → See all seven tool contracts →