> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Best practices

> This guide covers recommended patterns for configuring your Managed MCP servers, structuring plans, and handling common scenarios.

## Plan Configuration

### Free Tier Strategy

Always configure a free/default plan that provides:

* **Basic tools for discovery** - Let users try your service
* **Limited included usage** - Prevent abuse while allowing evaluation
* **Clear upgrade path** - Make it obvious how to get more

A well-designed free tier converts trial users to paid customers.

If your onboarding goal is frictionless adoption, start with an unlimited free tier by setting
`limit.cap` to `0` on the free plan. This keeps access auth-protected while removing usage
caps for early users.

### Start free, add paid plans later

For new MCP servers, a practical rollout is:

1. Bootstrap free-only with `POST /v1/sdk/products/mcp/bootstrap`
2. Launch and validate tool quality with real usage
3. Add paid plans later with `PUT /v1/sdk/products/:productRef/mcp/plans`

This lets you avoid pricing lock-in before you understand usage patterns.

### Tool Tiering

Structure your plans by tool access to create clear value differentiation:

| Plan           | Tools                                  | Included              | Price      |
| -------------- | -------------------------------------- | --------------------- | ---------- |
| **Free**       | `basic_search`, `list_items`           | 100 requests/month    | \$0        |
| **Pro**        | All Free + `advanced_search`, `export` | 10,000 requests/month | \$19/month |
| **Enterprise** | All tools + `admin_*`                  | Unlimited             | Custom     |

### Tiering Strategies

**By Feature Complexity:**

* Free: Read-only operations
* Pro: Write operations, exports
* Enterprise: Admin, bulk operations

**By Use Case:**

* Free: Personal/hobby use
* Pro: Professional use
* Enterprise: Team/organization use

**By Volume:**

* All tiers get same tools
* Differentiate by included limits

## Included usage

Included allowances are enforced through [meters](/plans/glossary) — every MCP tool call automatically records a usage event against a `tool:{toolName}` meter. Plans reference these meters to set limits.

### How meter-based included usage works

1. Each MCP tool gets an auto-created meter (e.g. `tool:search_documents`)
2. Every tool invocation records a usage event (fire-and-forget, non-blocking)
3. Usage-based and hybrid plans track requests through a per-unit `charge` and an optional `limit`
4. On each request, SolvaPay queries the meter timeseries and compares it to the plan's included cap

### Included settings

| Setting        | Option                      | Description                                                          |
| -------------- | --------------------------- | -------------------------------------------------------------------- |
| **Included**   | `limit.cap`                 | Requests included per period. `0` is unlimited                       |
| **On exceed**  | `limit.onExceed`            | `block` stops access; `charge` bills overage at the per-request rate |
| **Usage rate** | `charge` with `per: "unit"` | Money per request (minor units). Not a credit count                  |

Minimum top-up is a provider setting in SolvaPay Console, not a plan option. See [Auto-recharge](/sdks/typescript/guides/auto-recharge).

See [Plans](/plans/overview) for compositions and [Plans and billing glossary](/plans/glossary) for the credit peg and `cap: 0` sentinel.

### Overage options

1. **Hard cap** (`onExceed: "block"`) — stop requests when included usage is exhausted. The paywall includes a checkout URL.
2. **Overage** (`onExceed: "charge"`) — keep serving and bill usage beyond the included cap at the per-request rate
3. **Unlimited** (`cap: 0`) — no included cap
4. **Pay-as-you-go** — omit `limit`; every request is billed

### Included recommendations

* **Free tier:** Hard cap to prevent abuse (`limit.cap: 100`, `onExceed: "block"`)
* **Paid tiers:** Usage-based with generous included usage, or hybrid with overage (`onExceed: "charge"`)
* **Enterprise:** `limit.cap: 0` (unlimited) or a very high cap
* **Unlimited free tier:** `limit.cap: 0` means unlimited, not "zero included"

## Tool Assignment Patterns

### Default Plan Inclusion

The default plan is automatically included for all protected tools unless you explicitly select "No plan."

**When to keep default plan:**

* Tools that demonstrate value
* Basic functionality users expect
* Onboarding-essential tools

**When to remove default plan:**

* Premium-only features
* High-cost operations
* Advanced functionality

### Unprotected Tools

Mark tools as "No plan" when they should be:

* Freely accessible without authentication
* Not tracked for usage
* Utility tools that support other operations

Examples of good candidates for "No plan":

* `get_version` - Returns API version
* `list_capabilities` - Shows available features
* `ping` - Health check

## User Flow Optimization

### Onboarding Flow

Design your tool access to create a smooth onboarding experience:

1. **Discovery** - Free tools let users explore
2. **Value demonstration** - Users see what's possible
3. **Limitation encounter** - User hits paywall on premium feature
4. **Easy upgrade** - Virtual tools provide checkout path
5. **Activation** - Immediate access after payment

### Paywall Messaging

When users hit a paywall, the response should:

* Clearly explain what they're trying to access
* Identify which plan(s) provide access
* Include direct checkout links

AI agents can use this information to guide users naturally.

## Security best practices

### API Key Protection

If your origin server requires authentication:

* Store the API key in the Managed MCP settings (encrypted at rest)
* Never include it in client-facing URLs or responses
* Rotate keys periodically
* Use separate keys for Managed MCP vs direct access

### Origin Server Access

Consider restricting your origin server to only accept requests from SolvaPay:

* Whitelist SolvaPay IP ranges
* Require the API key for all requests
* Monitor for direct access attempts

## Monitoring and Analytics

### Key Metrics to Track

| Metric                      | What It Tells You               |
| --------------------------- | ------------------------------- |
| **Tool usage by plan**      | Which features drive upgrades   |
| **Conversion rate**         | Free-to-paid effectiveness      |
| **Quota utilization**       | If limits are appropriately set |
| **Error rates**             | Origin server health            |
| **Authentication failures** | User experience issues          |

### Console usage

Regularly review the Managed MCP section of the SolvaPay Console to:

* Monitor active users and usage patterns
* Identify popular and underused tools
* Track revenue and purchase metrics
* Spot anomalies or abuse patterns

## FAQ

### Can I use Managed MCP with any MCP server?

Yes, as long as your MCP server is accessible via HTTPS. SolvaPay connects to your origin URL to discover tools and proxies requests at runtime.

### How do users authenticate?

Users authenticate via OAuth 2.0 using their Google or GitHub account. When they add your MCP server to their client (like Cursor), a browser window opens for sign-in. No passwords or API keys to manage.

### What MCP clients are supported?

Any MCP client that supports OAuth 2.0 with PKCE can connect to Managed MCP servers. This includes Cursor, Claude Desktop, and other MCP-compatible tools. DCR support means clients can auto-configure themselves.

### How are origin server API keys handled?

If your origin MCP server requires authentication, you can configure an API key in the MCP server settings. This key is encrypted at rest and never exposed—SolvaPay uses it internally when forwarding requests to your origin server.

### What happens if my origin server is down?

The proxy will return an error to the client. SolvaPay does not cache responses or provide fallback behavior. Monitor your origin server availability.

### Can I change tool plan assignments after creation?

Yes, you can edit the MCP server configuration at any time. Changes take effect immediately for new tool invocations. Existing active sessions are not disrupted.

### How do I track usage and revenue?

The Managed MCP section of the SolvaPay Console shows transaction history, usage statistics, and revenue metrics. You can also view per-product stats from the product detail page.

### Can I customize the hosted pages?

All hosted pages (login, checkout, account portal) automatically display your provider branding including logo, colors, and fonts. Configure these in **Settings > Pages**. For advanced customization beyond branding, consider the SDK integration approach.

### Do I need to build payment or account pages?

No. Managed MCP provides fully hosted checkout and account management pages. Customers can purchase plans, manage their purchases, and view billing history without you building any UI. All pages are white-labeled with your branding.

### Can I migrate from the managed path to SDK integration later?

Yes. You can start with Managed MCP for quick setup and migrate to SDK integration if you need more control. Your plans, customers, and purchases remain intact—only the integration method changes.

### How do I handle refunds?

Refunds are processed through your Stripe dashboard. When you refund a payment:

1. The purchase may be cancelled depending on your refund settings
2. Tool access is adjusted based on new purchase status
3. Customer receives notification

### What if a customer disputes a charge?

Stripe handles disputes through their standard process. You'll receive notification and can provide evidence through the Stripe dashboard. During dispute resolution, the purchase typically remains active.

## Troubleshooting

### Tools Not Discovered

If tool discovery fails:

1. Verify origin URL is correct and accessible
2. Check API key if required
3. Ensure origin server responds to MCP protocol
4. Try accessing origin URL directly to verify it's online

### Users Can't Authenticate

If authentication fails:

1. Verify MCP server is active (not disabled)
2. Check proxy URL is correct
3. Ensure browser allows popups for OAuth
4. Try a different browser

### Tool Calls Failing

If authenticated tool calls fail:

1. Check user's purchase status
2. Verify tool is assigned to user's plan
3. Check if included usage is exhausted
4. Review origin server logs for errors

## Next Steps

* [Managed MCP overview](/no-code-mcp/overview) - Review core concepts
* [Quick start](/no-code-mcp/quick-start) - Set up your first product
* [Authentication](/no-code-mcp/authentication) - Deep dive into OAuth
* [Plans and billing glossary](/plans/glossary) - Credits, meter noun, included vs wallet remaining
* [Plans](/plans/overview) — compose pricing from options
* [Billing](/plans/billing) - Usage-based billing and end-of-period processing