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
- 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. - 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.
- Run. Your tool calls its upstream and reports what the call cost.
- Complete. The SDK settles the call at the reported cost. An upstream answer of
400or 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:
Paid tools
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. SetProtectedResource 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
401with the challenge that sends the host to sign in. - Set
TokenVerifierOptions.Resourceto the same URL, so tokens issued for it are accepted.
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.Checkdecides one call to an HTTP API: not an agent (your own auth decides), rejected, refused or allowed.RefusalStatusandWriteRefusalturn a refusal into an HTTP answer.Calls.Beginauthorizes a call and returns either*Allowedor*Refused. CallAllowed.Finishwith the upstream’s result, orAllowed.Releasewhen the upstream was never reached.Client.ReportUsagesends your upstream’s usage for reconciliation.
Next steps
- MCP server: the customer-facing server the route sits in front of.
- The TypeScript equivalent of this page: Agent payments.