Troubleshooting

Quick fixes for the most common PayMCP issues.

STDIO Mode Deployment Error

Error: STDIO mode disabled by PayMCP

Why this is dangerous: STDIO mode requires distributing your server (including API keys) to end users, exposing sensitive payment credentials.

Solution: Always use hosted deployment

Common Issues

Tool Not Found Error

Error: Tool 'my_tool' not found or similar MCP errors

Solution: Include ctx: Context parameter:

Python

# ❌ Wrong
@price(amount=0.50, currency="USD")
def process_user_input(input: str) -> str:
    return "result"

# ✅ Correct
@price(amount=0.50, currency="USD")
def process_user_input(input: str, ctx: Context) -> str:
    """Process user input and return result"""
    return "result"

TypeScript

// ❌ Wrong
mcp.tool("process_user_input", {
  price: { amount: 0.50, currency: "USD" }
}, async ({ input }) => {
  return { content: [{ type: "text", text: "result" }] };
});

// ✅ Correct
mcp.tool("process_user_input", {
  description: "Process user input and return result",
  price: { amount: 0.50, currency: "USD" }
}, async ({ input }, ctx) => {
  return { content: [{ type: "text", text: "result" }] };
});

Provider Authentication Error

Error: Invalid API key or Authentication failed

Solutions:

1. Check API key format:

   • Stripe: Should start with sk_test_ or sk_live_
   • Walleot: Should start with sk_test_ or sk_live_
   • PayPal: Check client ID and secret format

2. Verify environment variables:

Python

import os
print(f"Stripe key: {os.getenv('STRIPE_SECRET_KEY')[:10]}...")  # Check first 10 chars

TypeScript

console.log(`Stripe key: ${process.env.STRIPE_SECRET_KEY?.substring(0, 10)}...`);

Import Errors

Error: ModuleNotFoundError: No module named 'paymcp'

Solution: Install PayMCP:

Python

pip install paymcp

TypeScript

npm install paymcp

Provider Import Errors

Error: ImportError: cannot import name 'StripeProvider' from 'paymcp.providers'

Solution: Ensure you're using the latest PayMCP version:

Python

# Check version first
import paymcp
print(f"PayMCP version: {paymcp.__version__}")

# Then import provider classes
from paymcp.providers import StripeProvider, WalleotProvider

TypeScript

// Check version first
import paymcp from 'paymcp';
console.log(`PayMCP version: ${paymcp.version}`);

// Then import provider classes
import { StripeProvider, WalleotProvider } from 'paymcp/providers';

Configuration Problems

Error: TypeError: build_providers expects a mapping or an iterable of provider instances

Solution: Use the canonical provider list format:

Python

# ✅ Correct
from paymcp.providers import StripeProvider
PayMCP(mcp, providers=[StripeProvider(apiKey="sk_test_...")])

TypeScript

// ✅ Correct
import { StripeProvider } from 'paymcp/providers';
installPayMCP(mcp, { providers: [new StripeProvider({ apiKey: "sk_test_..." })] });

Missing Environment Variables

Error: NoneType errors when accessing API keys

Solution: Use environment file:

Python

# .env file
STRIPE_SECRET_KEY=sk_test_...
WALLEOT_API_KEY=sk_test_...
PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...

# Load in Python
from dotenv import load_dotenv
load_dotenv()

TypeScript

# .env file
STRIPE_SECRET_KEY=sk_test_...
WALLEOT_API_KEY=sk_test_...
PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...

# Load in Node.js
import dotenv from 'dotenv';
dotenv.config();

Coordination Mode Issues

ELICITATION Not Working

Error: Elicitation not supported or hangs indefinitely

Cause: MCP client doesn't support elicitation

Solution: Use the TWO_STEP coordination mode instead:

Python

PayMCP(
    mcp,
    providers={...},
    mode=Mode.TWO_STEP  # More compatible
)

TypeScript

installPayMCP(mcp, {
    providers: {...},
    mode: Mode.TWO_STEP  // More compatible
});

DYNAMIC_TOOLS Tool List Not Updating

Error: Confirmation tool never appears or tool list remains unchanged

Cause: MCP client doesn't send listChanged notifications or caches the tool list

Solutions:

• Confirm your MCP client supports dynamic tool lists before using Mode.DYNAMIC_TOOLS
• Fall back to Mode.TWO_STEP if the client ignores listChanged updates
• Restart the client session to clear cached tool metadata after enabling dynamic tools

Frequently Asked Questions

Q: How do I deploy PayMCP securely? A: Deploy PayMCP on your own infrastructure (AWS, GCP, Heroku, etc.) where:

• You control the server environment
• API keys are stored securely as environment variables
• Users connect via HTTP/WebSocket protocols
• No sensitive credentials are distributed to users

Q: Can I use multiple payment providers simultaneously? A: Yes! PayMCP supports multiple configuration methods. PayMCP currently uses the first configured provider.

Q: What's the minimum payment amount? A: Depends on the provider:

• Stripe: $0.50 USD minimum
• PayPal: $0.01 USD minimum
• Walleot: No minimum
• Square: $1.00 USD minimum

Getting Help

Debug Mode

Enable detailed logging for troubleshooting:

Python

import logging
logging.basicConfig(level=logging.DEBUG)

# PayMCP will log:
# - Provider API calls and responses
# - Coordination mode decisions
# - Error details and stack traces

TypeScript

// Enable debug logging
process.env.DEBUG = 'paymcp:*';

// PayMCP will log:
// - Provider API calls and responses
// - Coordination mode decisions
// - Error details and stack traces

Support Channels

1. GitHub Issues: PayMCP Issues
2. Documentation: This documentation site
3. Provider Support: Use provider specific channels

Reporting Bugs

When reporting issues, include:

1. PayMCP version: paymcp.__version__
2. MCP version: mcp.__version__
3. Provider: Which provider you're using
4. Mode: TWO_STEP, RESUBMIT, ELICITATION, etc.
5. Error messages: Full error text and stack traces
6. Code sample: Minimal reproducible example

Next Steps

• Back to Quickstart - If you're just getting started
• Provider Guides - Provider-specific help
• Examples - Working code examples
• API Reference - Detailed parameter documentation