Skip to main content
Agent payments are in preview. SolvaPay has to turn them on for your merchant account before agents can pay you. Until then, SolvaPay refuses every paid call: a call with an agent token is refused with the reason unavailable, and a request with an agent key fails with a 500 that the route logs.
The agents package (github.com/solvapay/solvapay-sdk/go/agents) lets an AI agent pay for your MCP tools on its owner’s behalf. The agent presents a SolvaPay credential instead of a customer sign-in, and SolvaPay decides each call against the owner’s spend policy, budget and balance, asking the owner to approve it when the policy says so.

How a paid call works

  1. Identify. The agent presents a SolvaPay agent token (a JWT from SolvaPay’s agent issuer) or an agent key (agk_…). The SDK verifies a token against SolvaPay’s published keys, and asks SolvaPay about a key, reusing the answer for 30 seconds.
  2. Authorize. Before your tool runs, the SDK asks SolvaPay whether the call may go ahead, with your estimate of its cost. SolvaPay holds that amount, refuses the call, or waits for the owner’s approval.
  3. Run. Your tool calls its upstream and reports what the call cost.
  4. Complete. The SDK settles the call at the reported cost. An upstream answer of 400 or above charges nothing. If your tool returns an error, the upstream was never reached: the call is released and nothing is charged.

Add agent payments to an MCP server

NewMCPRoute answers agents on your MCP path. Middleware puts it in front of your own handler: requests that carry an agent credential go to the route, and everything else reaches your handler unchanged, for example the Handler() of a NewMCPServer.
main.go
issuer is SolvaPay’s agent token issuer. Only bearer tokens from this issuer, and agent keys, go to the agent route, and the SDK fetches its public keys from <issuer>/jwks.json. Set these in your environment: AddPaidTool(paid, tool) registers a paid tool inside Tools. PaidTool[Args] decodes the arguments into Args and, when InputSchema is nil, infers the schema from it. FreeTools registers tools anyone may call, signed in or not, on the *mcp.Server it is given.

Sign-in for hosts

Hosts such as Claude and ChatGPT get an agent token by OAuth. Set ProtectedResource to turn this on:
  • The route serves the resource’s metadata at /.well-known/oauth-protected-resource/mcp, naming SolvaPay’s agent issuer as the authorization server.
  • A paid call without a token gets a 401 with the challenge that sends the host to sign in.
  • Set TokenVerifierOptions.Resource to the same URL, so tokens issued for it are accepted.
By default a host may list tools and run free ones before sign-in. SignInFirst: true challenges every tool call without a token.

Refusals

A refused call is a tool error (isError). Its text is the sentence for the agent’s owner, and structuredContent.refusal.reason says which refusal it was, so the agent can act without parsing the text: CallsOptions.MaxWaitSeconds is how long a call may wait for the owner’s approval; 0 refuses at once. Each authorize request holds for at most 55 seconds, so a longer wait is a series of requests.

HTTP APIs and your own flow

The MCP route is built from smaller parts you can use directly:
  • Gate.Check decides one call to an HTTP API: not an agent (your own auth decides), rejected, refused or allowed. RefusalStatus and WriteRefusal turn a refusal into an HTTP answer.
  • Calls.Begin authorizes a call and returns either *Allowed or *Refused. Call Allowed.Finish with the upstream’s result, or Allowed.Release when the upstream was never reached.
  • Client.ReportUsage sends your upstream’s usage for reconciliation.
See the package reference for each type.

Next steps

  • MCP server: the customer-facing server the route sits in front of.
  • The TypeScript equivalent of this page: Agent payments.