create_solvapay_mcp_server builds an MCP server on the official MCP Python SDK. Customers sign in with SolvaPay over OAuth. Each paid tool call is checked against the customer’s plan before your handler runs. A call that isn’t allowed returns the paywall: a message that names the next step, with a checkout link.
Prerequisites
pip install 'solvapay[mcp]' uvicornSOLVAPAY_SECRET_KEYandSOLVAPAY_PRODUCT_REFset. See Installation.- A public HTTPS URL for the server. In development, use a tunnel such as ngrok.
npm create solvapay@latest my-mcp-server -- --type mcp --language python: it scaffolds this server with one paid and one free tool, tests and a Dockerfile.
Create the server
Save this asserver.py:
ResponseContext, become the tool’s input schema. Use Annotated[str, Field(description=...)] to describe a parameter to the model. The handler must return ctx.respond(...).
register_payable adds a hint to the description that tells the model the tool is paid and that account shows the cost. Pass product="prd_..." to bill a tool against another product.
Run it locally
1
Start a tunnel
https://research-dev.ngrok.app.2
Start the server
3
Connect a client
Add
https://research-dev.ngrok.app/mcp to an MCP client (Claude, ChatGPT, Cursor, MCP Inspector) as a remote server. The client opens SolvaPay’s sign-in, then can call the tools.Why public_base_url must match the client’s URL
public_base_url is the URL clients use to reach the server. The server uses it in three places:
- OAuth. It’s the issuer and resource in the server’s discovery documents, and the
WWW-Authenticatechallenge points at it. If it doesn’t match the URL the client connected to, sign-in fails. - Host check. The MCP SDK’s DNS-rebinding protection allows only this host and localhost. A request through any other host gets a
421. - 3-D Secure. Stripe sends the customer back to this URL after a 3-D Secure check.
PUBLIC_BASE_URL and restart.
How customer sign-in works
The server acts as the OAuth authorization server the client sees, and forwards each step to SolvaPay:- An unauthenticated request to
/mcpgets a401pointing at/.well-known/oauth-protected-resource. - The client reads
/.well-known/oauth-authorization-server, registers at/oauth/register(for your product), and sends the customer to/oauth/authorize, which redirects to SolvaPay’s sign-in. - The client exchanges the code at
/oauth/token. - On each request, the server checks the bearer token with SolvaPay and caches a valid token for 60 seconds. Your tools see the customer SolvaPay verified, never a value read from an unchecked token.
get_customer_ref= to create_solvapay_mcp_server or to register_payable. It receives the tool arguments and the MCP Context, and returns the customer reference.
Shape the answer with ResponseContext
If the handler raises, the tool returns an error result with the exception’s message and the call is recorded as failed.
Add a free tool with a cap
register_free registers a tool that is free up to a per-customer cap you set in code. When the cap is reached, the tool returns the same paywall as a paid tool.
scopeisrolling_window(needswindow_days) orlifetime.meterdefaults tofree-requestsand must matchfree-[a-z0-9-]+. Tools that name the same meter share one free allowance, and must declare the sameFreeLimit, or registration raisesinvalid_free_limit.- Free tools need a signed-in customer too.
Built-in tools and prompts
Every server comes with SolvaPay’s built-in tools, free to call:
It also registers the
/upgrade, /manage_account, /topup and /activate_plan prompts and the docs://solvapay/overview.md resource. Paywall messages name account as the way to pay.
The checkout widget
On hosts that support MCP Apps (ChatGPT, Claude),account opens SolvaPay’s checkout and account widget in the chat. It’s the same widget the TypeScript SDK serves, and it ships in the package. Text-only hosts get the same answer as text with links, and mode: "text" asks for text on any host.
The widget pays, tops up and manages renewals through six tools only it calls: create_payment_intent, process_payment, create_hosted_session, set_renewal, attach_business_details and get_history. They’re marked for the app (_meta.ui.visibility: ["app"]), so MCP Apps hosts keep them from the model.
Options on create_solvapay_mcp_server:
Other options:
instructions, version, mcp_path (default /mcp), oauth_paths and http_client.
Next steps
- Examples: a complete paid MCP server.
- Agent payments (preview): let SolvaPay agents pay per call.
- The TypeScript equivalent is the MCP server guide.