Prerequisites
pip install 'solvapay[agents,mcp]' uvicorn- Agent payments turned on for your merchant account
- These environment variables:
Serve a paid tool to agents
route.middleware(app) answers requests on /mcp that carry an agent token or agent key (agk_...), and passes every other request to your app. To keep serving signed-in customers on the same /mcp, pass your paid MCP server’s http_app() as the app. You can also call await route(request) from your own handler: it returns a response for an agent’s request, or None.
What happens on a paid call
- Identify.
AgentLayertells an agent’s credential from your own.AgentTokenVerifierchecks agent tokens (ES256 JWTs) against SolvaPay’s keys at<issuer>/jwks.json.AgentKeyVerifierasks SolvaPay whose an agent key is and reuses the answer for 30 seconds. - Authorize.
AgentCallssends the call’sitemandestimateto SolvaPay. When the owner must approve, it waits up tomax_wait_seconds(0 refuses at once). Keep it under your MCP client’s timeout, and the API client’stimeoutabove it. - Run. Your
runcalls the upstream and returns aPaidToolRunwith the upstream’sstatus, the reportedcostas(amount, currency), and theresultfor the agent. - Complete. SolvaPay settles the call at the reported cost. A
statusof 400 or above charges nothing. Ifrunraises, the hold is released and nothing is charged.
PaidTool fields:
Refusals
A refused call is a tool error (isError: true). Its text is a sentence for the agent’s owner, and structuredContent.refusal.reason says which refusal it was, so an agent can act on it without parsing text:
refusal_status(reason) gives the matching HTTP status if you serve agents outside MCP: 402, 422, 401 or 502.
Sign-in for hosts such as Claude and ChatGPT
By default, agents bring their own token or agent key. To let hosts sign in with SolvaPay’s agent OAuth, passprotected_resource=ProtectedResource(resource="https://research.example.com/mcp") to create_agent_mcp_route, and the same URL as resource= to AgentTokenVerifier. The route then serves the protected-resource document and challenges a paid call that has no token. free_tools= registers tools anyone can call, signed in or not.
Next steps
- Paid MCP server: serve signed-in customers.
- API client:
AsyncApiClientoptions.