Best Practices

​

Plan Configuration

​

Free Tier Strategy

Always configure a free/default plan that provides:

• Basic tools for discovery - Let users try your service
• Limited quota - 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.

​

Tool Tiering

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

​

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 quota limits

​

Quota Management

Quotas are enforced through meters — every MCP tool call automatically records a meter event against a tool:{toolName} meter. Plans reference these meters to set limits.

​

How Meter-Based Quotas Work

1. Each MCP tool gets an auto-created meter (e.g. tool:search_documents)
2. Every tool invocation records a meter event (fire-and-forget, non-blocking)
3. Usage-based and hybrid plans automatically track requests and define a limit
4. On each request, SolvaPay queries the meter timeseries to check current usage against the plan’s limit

​

Quota Settings

​

Overage Options

1. Hard limit (limit with no overage policy) - Block requests when quota exhausted. The paywall response includes a checkout URL.
2. Soft limit (hybrid plan with overagePolicy.allowOverage: true) - Allow continued use, charge overage at overageRate per unit up to maxOverage
3. Unlimited (limit: 0) - No cap on usage

​

Quota Recommendations

• Free tier: Hard limit to prevent abuse (e.g. limit: 100, freeUnits: 100)
• Paid tiers: Usage-based with generous limits or hybrid with overage
• Enterprise: limit: 0 (unlimited) or very high limits

​

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 MCP Pay settings (encrypted at rest)
• Never include it in client-facing URLs or responses
• Rotate keys periodically
• Use separate keys for MCP Pay 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

​

Dashboard Usage

Regularly review the MCP Pay dashboard 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 MCP Pay 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 MCP Pay 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 MCP Pay dashboard 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. MCP Pay 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 MCP Pay to SDK integration later?

Yes. You can start with MCP Pay 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 quota is exhausted
4. Review origin server logs for errors

​

Next Steps

• MCP Pay Overview - Review core concepts
• Quick Start - Set up your first product
• Authentication - Deep dive into OAuth
• Meters - Meter definitions and auto-created tool meters
• Plans - Plan types and meter-based pricing
• Billing - Usage-based billing and end-of-period processing