Skip to main content
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]' uvicorn
  • SOLVAPAY_SECRET_KEY and SOLVAPAY_PRODUCT_REF set. See Installation.
  • A public HTTPS URL for the server. In development, use a tunnel such as ngrok.
To start from a working project instead, run 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 as server.py:
A handler is an async function. Its parameters, except the 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

Copy the HTTPS forwarding URL, such as 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-Authenticate challenge 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.
When the tunnel URL changes, update 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:
  1. An unauthenticated request to /mcp gets a 401 pointing at /.well-known/oauth-protected-resource.
  2. 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.
  3. The client exchanges the code at /oauth/token.
  4. 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.
A tool call with no signed-in customer is refused. There’s no anonymous fallback, and a tool argument is never trusted as the customer. To take the customer from your own auth, pass 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.
  • scope is rolling_window (needs window_days) or lifetime.
  • meter defaults to free-requests and must match free-[a-z0-9-]+. Tools that name the same meter share one free allowance, and must declare the same FreeLimit, or registration raises invalid_free_limit.
  • Free tools need a signed-in customer too.
See the TypeScript free allowance guide for how the allowance is counted.

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