Skip to main content
This is the recommended path for teams that already have an MCP server and want fast monetization without building billing/auth infrastructure.

​
Prerequisites

  • SolvaPay provider account
  • Origin MCP server URL available over HTTPS
  • Pricing plan decisions ready for product setup (you will configure plans during product creation)

​
Step 1: Create Product and Select Plans

Start in Products, complete product details, then select at least one plan in the Plans step. If you are in onboarding, this can be your guided first product flow.

​
Step 2: Enable Hosted MCP Pay Configuration

In the Integration step, enable and configure Hosted MCP Pay:
  • MCP URL slug (public endpoint slug)
  • Origin MCP server URL (your upstream MCP endpoint)
  • Optional auth settings, if required

​
Step 3: Create Product and Verify MCP Server URL

After creating the product, open the product details page and confirm:
  • Product is active
  • Hosted MCP integration is enabled
  • Generated MCP server URL is present and copyable

​
Step 4: Use Connect for quick client testing

From the product overview, click Connect to test your configured MCP Server product without manual setup. Use the menu option that matches your workflow:
  • Copy MCP URL to paste into any MCP client manually
  • Connect to Claude to open the Claude connection flow
  • Connect to Cursor to open the Cursor connection flow
If you do not use a listed client, copy the MCP URL and connect in your preferred MCP client.

​
User Onboarding Behavior

When users connect to the hosted MCP server URL:
  1. They authenticate via SolvaPay-hosted OAuth
  2. SolvaPay evaluates plan access for requested tools
  3. Usage and billing are handled through your configured plans

​
What to Do Next

​
API quickstart (SDK bootstrap endpoint)

If you want the same setup flow through API, use the SDK bootstrap route: POST /v1/sdk/products/mcp/bootstrap This creates in one call:
  • MCP-enabled product
  • free plan settings
  • paid plans (for example pro)
  • origin URL configuration
  • tool-to-plan mapping
Canonical request fields are:
  • originUrl
  • freePlan
  • paidPlans
  • tools[].noPlan
  • tools[].planIds (or planRefs / planKeys during bootstrap)
curl -X POST "https://api.solvapay.com/v1/sdk/products/mcp/bootstrap" \
  -H "Authorization: Bearer $SOLVAPAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docs Assistant",
    "originUrl": "https://origin.example.com/mcp",
    "freePlan": {
      "name": "Free",
      "freeUnits": 1000
    },
    "paidPlans": [
      { "key": "pro", "name": "Pro", "price": 2000, "currency": "USD", "billingCycle": "monthly" }
    ],
    "tools": [
      { "name": "list_docs", "planKeys": ["free"] },
      { "name": "deep_research", "planKeys": ["pro"] },
      { "name": "health_check", "noPlan": true }
    ]
  }'
Free-only bootstrap is also valid. This is useful when you want to launch with a free tier first and add paid plans later: 
curl -X POST "https://api.solvapay.com/v1/sdk/products/mcp/bootstrap" \
  -H "Authorization: Bearer $SOLVAPAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docs Assistant",
    "originUrl": "https://origin.example.com/mcp",
    "freePlan": {
      "name": "Free",
      "freeUnits": 0
    }
  }'
freeUnits: 0 on the free tier means unlimited free access for authenticated users. Use this for the fastest onboarding. If you need fine-grained lifecycle control, use the granular product, plan, and MCP server endpoints.

​
Configure plans after bootstrap

After the product exists, use: PUT /v1/sdk/products/:productRef/mcp/plans This endpoint lets you update free-plan settings, replace paid plans, and remap tool access. Request fields:
  • freePlan (required) — updates the existing default free plan
  • paidPlans (optional) — replace paid plans, remove all paid plans ([]), or leave unchanged (omit)
  • toolMapping (optional) — explicit tool-to-plan mapping by plan keys
Response fields:
  • product
  • mcpServer
  • planMap

​
Mode 1: add or replace paid plans

curl -X PUT "https://api.solvapay.com/v1/sdk/products/prd_1A2B3C4D/mcp/plans" \
  -H "Authorization: Bearer $SOLVAPAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "freePlan": {
      "name": "Free",
      "freeUnits": 100
    },
    "paidPlans": [
      { "key": "pro", "name": "Pro", "price": 2000, "currency": "USD", "billingCycle": "monthly" },
      { "key": "team", "name": "Team", "price": 6000, "currency": "USD", "billingCycle": "monthly" }
    ],
    "toolMapping": [
      { "name": "list_docs", "planKeys": ["free", "pro", "team"] },
      { "name": "deep_research", "planKeys": ["pro", "team"] }
    ]
  }'

​
Mode 2: revert to free-only

Set paidPlans to [] to remove all paid plans and remap protected tools to free: 
curl -X PUT "https://api.solvapay.com/v1/sdk/products/prd_1A2B3C4D/mcp/plans" \
  -H "Authorization: Bearer $SOLVAPAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "freePlan": {
      "name": "Free",
      "freeUnits": 0
    },
    "paidPlans": []
  }'

​
Mode 3: remap tools without changing plans

Omit paidPlans and pass only toolMapping: 
curl -X PUT "https://api.solvapay.com/v1/sdk/products/prd_1A2B3C4D/mcp/plans" \
  -H "Authorization: Bearer $SOLVAPAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "freePlan": {
      "name": "Free",
      "freeUnits": 1000
    },
    "toolMapping": [
      { "name": "deep_research", "planKeys": ["pro"] },
      { "name": "list_docs", "planKeys": ["free", "pro"] }
    ]
  }'

​
Tool and default-plan precedence

When SolvaPay evaluates access for a tool:
  1. If tools[].noPlan is true, the tool is public.
  2. Otherwise, SolvaPay checks if the user’s purchase plan is in:
    • tools[].planIds, or
    • the MCP server defaultPlanId.

​
Troubleshooting bootstrap errors

Common validation failures for POST /v1/sdk/products/mcp/bootstrap:
  • UNKNOWN_PLAN_KEY
    A tool references a planKeys value not declared in paidPlans[].key (or free).
  • UNKNOWN_PLAN_REFERENCE
    tools[].planRefs points to a plan not created by the same bootstrap request.
  • PLAN_PRODUCT_MISMATCH
    tools[].planIds includes a plan ID outside the plans created in this bootstrap call.
  • DUPLICATE_TOOL_NAME
    The same tool name appears more than once in tools.
  • origin URL validation error (originUrl)
    originUrl must be a valid https:// URL.
Common validation failures for PUT /v1/sdk/products/:productRef/mcp/plans:
  • MISSING_REQUIRED_FIELD
    freePlan is required.
  • NOT_MCP_PRODUCT
    The product is not MCP-enabled.
  • NO_MCP_SERVER
    No MCP server is linked to the product.
  • DEFAULT_FREE_PLAN_NOT_FOUND
    The product is missing a default free plan.
  • UNKNOWN_PLAN_KEY
    A toolMapping[].planKeys entry does not match free or a paid plan key in the same request.