Skip to main content
NewMCPServer builds an MCP server on the official MCP Go SDK. Customers sign in with SolvaPay over OAuth, every paid tool call is checked against the customer’s plan, and SolvaPay’s own tools let the customer pick a plan, pay and manage their account without leaving the chat.

Prerequisites

  • The Go SDK installed and SOLVAPAY_SECRET_KEY and SOLVAPAY_PRODUCT_REF set. See Installation.
  • A public HTTPS URL for your server. In development, use a tunnel such as ngrok (see Run it locally).
To start from a working project instead, run npm create solvapay@latest my-mcp-server -- --type mcp --language go: it scaffolds this server with one paid and one free tool, tests and a Dockerfile.

Create a server with a paid tool

main.go
Handler() serves the MCP endpoint at /mcp and the sign-in routes. Each call to get_quote goes through the paywall first: a customer with a plan gets the answer and the call is recorded as usage; a customer without one gets the paywall with a checkout link. MCPServerOptions needs a Client, a PublicBaseURL and a product (ProductRef or SOLVAPAY_PRODUCT_REF). NewMCPServer fails otherwise. RegisterPayable(name, tool) adds a paid tool. A PaidTool has: A handler gets the call’s arguments as json.RawMessage and a *ResponseContext. Any error other than a gate is returned to the model as a tool error with its message, and the call is recorded as failed.

Free tools

RegisterFree(name, limit, tool) adds a tool with a free allowance. The customer gets limit.Cap calls per window, then needs a plan. The SDK adds the allowance to the tool’s description.
FreeLimit.Meter names the free meter (free- followed by lowercase letters, digits or dashes); empty means free-requests. Tools that name the same meter share one allowance, and must declare the same limit. Free tools also need a signed-in customer. See Free allowance for how the allowance is counted.

Answer with the response context

ResponseContext is the handler’s view of the call:
  • rc.Customer is the customer as the limits check saw them: Ref, Balance, Remaining, WithinLimits, Overage, IsCreditBased and Plan. It may be as old as the paywall’s limits cache (10 seconds by default); rc.Customer.Fresh(ctx) asks the API again.
  • rc.Product.Reference is the product the call is charged to.
  • rc.Respond(data, options) is the answer. data is sent as JSON text and, when it is an object, as structured content.
  • rc.Gate(reason) stops the call and shows a paywall instead. Return the error it gives. Nothing is recorded as usage.
  • rc.Emit(block) queues a content block (text, image or resource) ahead of the answer.
RespondOptions.Nudge appends a soft prompt to a successful answer: NudgeLowBalance, NudgeCycleEnding or NudgeApproachingLimit. An empty Message uses the paywall’s default text. Text replaces the JSON text of the data, and OmitDataText leaves the data out of the content when Text or Nudge is set.

Built-in tools, prompts and the checkout widget

NewMCPServer adds these next to your tools:
  • account: shows the customer’s plan, balance and payment method, opens checkout to pick a plan, or tops up credits.
  • activate_plan: starts a plan for the customer.
  • Widget tools: six tools only the checkout widget calls (create_payment_intent, process_payment, create_hosted_session, attach_business_details, get_history, set_renewal). They are marked app-only in _meta.ui.visibility, so MCP Apps hosts keep them out of the model’s tool list.
  • Prompts: /upgrade, /manage_account, /topup and /activate_plan.
  • Resources: docs://solvapay/overview.md (a start-here document for the model), solvapay://bootstrap.json, and the checkout widget at ui://<Name>/mcp-app.html.
The widget is an MCP App: hosts that render MCP Apps show checkout, the account and top-ups inside the chat. Card payments use Stripe Elements. Hosts that don’t render it get the same answers as text with links. These options change what is added:
To add your own tools, prompts or resources without SolvaPay’s paywall, use the underlying server: server.Server() returns the *mcp.Server.

How customer sign-in works

MCP clients sign the customer in with OAuth. Your server is the authorization server the client sees, and forwards each step to SolvaPay: /mcp answers only requests whose bearer token SolvaPay verifies. The SDK asks SolvaPay who the token belongs to, and caches accepted tokens for 60 seconds. Every other request gets a 401 whose WWW-Authenticate header points the client at the protected-resource document, which starts sign-in. A tool sees the customer SolvaPay named for the token.

Set PublicBaseURL to the URL clients use

PublicBaseURL is the OAuth issuer and resource clients see, and where Stripe sends the customer back after 3-D Secure. It must be exactly the URL clients connect to, without /mcp. If it differs (for example http://localhost:3031 while clients use an ngrok URL), the issuer clients see doesn’t match the server they connected to, and sign-in fails.

Run it locally

  1. Start a tunnel to your port:
  2. Start the server with the tunnel’s URL:
  3. Add https://<your-tunnel>.ngrok.app/mcp to an MCP client as a remote server. The client opens SolvaPay’s sign-in, then can call your tools.

Next steps

  • Examples: a complete paid MCP server with six tools.
  • Agent payments: let agents pay for the same tools (preview).
  • The TypeScript equivalent of this page: MCP Server.