Integration
Connect MCPay-protected servers to MCP clients (Claude Desktop, Windsurf, etc.) or integrate programmatically with the SDK/CLI.
Financial Server Integration Guide
Using the Registry: This guide integrates one example server so you can copy–paste quickly. To use any other service, browse the MCPay Registry and replace the MCP URL below with the server you want.
Example MCP URL (replace with any from the Registry):
https://mcpay.tech/mcp/d67aaf0d-fcc8-4136-948d-c470abe41ac0
Prerequisite: API Keys (optional, recommended)
You don’t always need an API key (wallet-based x402 works without one), but for most desktop clients and quick SDK setups an MCPay API key is the simplest path.
Use a key when:
- You want easy, revocable auth without managing a wallet.
No key needed when:
- You’re using a wallet (pay → retry flow).
Get an API key
- Sign in to MCPay → Open the connection modal
- Go to API Keys → Add New Key
- Store it in an env var (e.g.,
MCPAY_API_KEY) - Rotate or revoke keys anytime in the modal
MCP Client Integration
Connect this server to MCP-aware tools (e.g., Claude Desktop, Windsurf).
Manual Configuration (API Key — recommended)
Create an API key (see Prerequisite above), then add this to your MCP client config (e.g., claude_desktop_config.json):
{
"mcpServers": {
"Financial Server": {
"command": "npx",
"args": [
"mcpay",
"server",
"--urls",
"https://mcpay.tech/mcp/d67aaf0d-fcc8-4136-948d-c470abe41ac0",
"--api-key",
"mcpay_YOUR_API_KEY_HERE"
]
}
}
}Tip: To integrate a different server, grab its MCP URL from the Registry and swap it into
--urls. You can also load the API key from an env var rather than inlining it.
Manual Configuration (Private Key — alternative)
{
"mcpServers": {
"Financial Server": {
"command": "npx",
"args": [
"mcpay",
"server",
"--urls",
"https://mcpay.tech/mcp/d67aaf0d-fcc8-4136-948d-c470abe41ac0",
"--private-key",
"0xYOUR_PRIVATE_KEY"
]
}
}
}⚠️ Security: Prefer API keys for desktop clients. If you must use a private key, load it from a secure env/keychain.
Direct API Integration (Programmatic)
Build custom apps that call tools programmatically. Pick one of two transports:
- Wallet (x402 payments): automatic
402pay → retry flow using an on-chain wallet. - HTTP + API key (no wallet): simple auth with an API key.
Replace the MCP URL with any server from the MCPay Registry. Example used below:
https://mcpay.tech/mcp/d67aaf0d-fcc8-4136-948d-c470abe41ac0
Option 1 — Wallet payment via SDK (x402)
Handles HTTP 402 automatically: receives price metadata → pays on-chain → retries.
import { Client } from '@modelcontextprotocol/sdk/client'
import { createPaymentTransport } from 'mcpay/client'
import { privateKeyToAccount } from 'viem/accounts'
const account = privateKeyToAccount(process.env.PRIVATE_KEY!) // use a secure signer in prod
const url = new URL('https://mcpay.tech/mcp/d67aaf0d-fcc8-4136-948d-c470abe41ac0') // ← replace from Registry
const transport = createPaymentTransport(url, account, {
// hard cap per-call spend (base units; 6 decimals for USDC). 0.1 USDC = 100_000
maxPaymentValue: BigInt(100_000)
})
const client = new Client({ name: 'my-mcp-client', version: '1.0.0' }, { capabilities: {} })
await client.connect(transport)
const tools = await client.listTools()
console.log('Available tools:', tools)Option 2 — HTTP transport with API key (no wallet)
Use an API key (from Prerequisite) and the MCP SDK’s Streamable HTTP transport.
import { Client } from '@modelcontextprotocol/sdk/client'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const mcpayApiKey = process.env.MCPAY_API_KEY
const url = new URL(`https://mcpay.tech/mcp/d67aaf0d-fcc8-4136-948d-c470abe41ac0?apiKey=${mcpayApiKey}`)
const transport = new StreamableHTTPClientTransport(new URL(url));
const client = new Client({ name: 'my-mcp-client', version: '1.0.0' }, { capabilities: {} })
await client.connect(transport)
const tools = await client.listTools()
console.log('Available tools:', tools)