MCP Billing Gateway
Billing proxy for MCP servers. Adds Stripe and x402 crypto payments without writing billing code.
Open source Repository Open in the app JSON README (API)
About
Billing proxy for MCP servers. Adds Stripe and x402 crypto payments without writing billing code.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- sapph1re
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.1.3
- Stars
- 2
- Last push
- 2026-08-19T20:00:35Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:01:21
- Updated
- 2026-08-29 04:01:21
- Origin id
io.github.sapph1re/mcp-billing-gateway
README
<!-- mcp-name: io.github.sapph1re/mcp-billing-gateway -->
# MCP Billing Gateway
[](https://glama.ai/mcp/servers/sapph1re/mcp-billing-gateway-sdk)
[](https://mcp.directory/servers?q=mcp-billing-gateway)
Add **Stripe subscriptions**, **per-call credits**, and **x402 crypto payments** to any MCP server — without writing billing code.
MCP Billing Gateway is a hosted billing proxy that sits between AI agents and your MCP server. It handles payment verification, usage tracking, and tier enforcement automatically. You register your server, set a pricing plan, and point callers to the proxied URL. No billing code required.
Live service: **https://mcp-billing-gateway-production.up.railway.app**
**Tutorial:** [Monetize any MCP server in 10 minutes](https://github.com/sapph1re/mcp-billing-demo) — step-by-step demo with working code
## Installation
```bash
pip install mcp-billing-gateway
```
Or with [uvx](https://docs.astral.sh/uv/):
```bash
uvx mcp-billing-gateway
```
### Configuration for Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"mcp-billing-gateway": {
"command": "uvx",
"args": ["mcp-billing-gateway"]
}
}
}
```
### Configuration for Cursor
Add to `.cursor/mcp.json` in your project:
```json
{
"mcpServers": {
"mcp-billing-gateway": {
"command": "uvx",
"args": ["mcp-billing-gateway"]
}
}
}
```
Restart your editor after adding the configuration to activate the MCP server.
## Tools
| Tool | Description |
|------|-------------|
| `get_billing_info` | Returns service capabilities, supported payment methods, features, and integration docs |
The local MCP server provides service discovery. The full billing functionality runs on the hosted gateway — register as an operator and proxy your MCP servers through it.
## How it works
```
AI Agent → MCP Billing Gateway → Your MCP Server
(billing enforced here)
```
1. Register as an operator and get an API key
2. Register your MCP server URL + pricing plan
3. Point callers to your proxy slug: `https://mcp-billing-gateway-production.up.railway.app/proxy/{your-slug}/mcp`
4. Callers pay via Stripe API key or x402 USDC — billing is handled transparently
## Features
- **Per-call billing** — charge callers per tool call (fiat or crypto)
- **Subscriptions** — monthly/annual Stripe plans with call limits
- **Tiered pricing** — free tier + paid tiers based on usage
- **x402 micropayments** — accept USDC on Base from AI agents with no API keys
- **Operator dashboard** — track revenue, usage, and callers in real time
- **MCP transport** — full Streamable HTTP MCP transport at `/mcp/` endpoint
## Quick Start
### 1. Register as operator
```bash
curl -X POST https://mcp-billing-gateway-production.up.railway.app/api/v1/operator/register \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com", "name": "Your Name"}'
```
Response:
```json
{
"operator_id": "op_abc123",
"api_key": "bg_live_xxxxxxxxxxxx",
"message": "Operator registered successfully"
}
```
### 2. Register your MCP server
```bash
curl -X POST https://mcp-billing-gateway-production.up.railway.app/api/v1/servers \
-H "Authorization: Bearer bg_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"name": "My MCP Server",
"upstream_url": "https://your-mcp-server.com/mcp",
"proxy_slug": "my-server"
}'
```
### 3. Create a pricing plan
```bash
curl -X POST https://mcp-billing-gateway-production.up.railway.app/api/v1/servers/{server_id}/plans \
-H "Authorization: Bearer bg_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"name": "Pay as you go",
"billing_model": "per_call",
"price_per_call_usd_micro": 10000,
"free_calls_per_month": 100
}'
```
### 4. Connect callers to your proxied server
```json
{
"mcpServers": {
"my-server": {
"url": "https://mcp-billing-gateway-production.up.railway.app/proxy/my-server/mcp",
"headers": {
"Authorization": "Bearer CALLER_API_KEY"
}
}
}
}
```
## Payment Methods
| Method | Best for | How |
|--------|----------|-----|
| Stripe subscription | Human developers | Monthly or annual plan via Stripe Checkout |
| Stripe per-call | Human developers | Credits consumed per tool call |
| x402 micropayments | AI agents | USDC on Base, no API keys needed |
## Examples
### Check gateway capabilities
```python
# Using the MCP client
result = await session.call_tool("get_billing_info")
print(result)
# {
# "service": "MCP Billing Gateway",
# "version": "0.1.0",
# "payment_methods": ["stripe_subscription", "stripe_metered", "x402_crypto"],
# "features": ["Per-call usage tracking", "Tiered pricing", ...],
# "live_service": "https://mcp-billing-gateway-production.up.railway.app"
# }
```
### Register and monetize an existing MCP server
```bash
# 1. Register
API_KEY=$(curl -s -X POST .../api/v1/operator/register \
-H "Content-Type: application/json" \
-d '{"email": "dev@example.com", "name": "Dev"}' | jq -r .api_key)
# 2. Add your server
SERVER_ID=$(curl -s -X POST .../api/v1/servers \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "my-tool", "upstream_url": "https://my-tool.com/mcp", "proxy_slug": "my-tool"}' \
| jq -r .server_id)
# 3. Set pricing: $0.01 per call, 100 free calls/month
curl -X POST .../api/v1/servers/$SERVER_ID/plans \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Starter", "billing_model": "per_call", "price_per_call_usd_micro": 10000, "free_calls_per_month": 100}'
# Callers now connect via: .../proxy/my-tool/mcp
```
## Operator Dashboard
Access your dashboard at:
```
https://mcp-billing-gateway-production.up.railway.app/dashboard
```
Track revenue, usage, active callers, and configure your servers in real time.
## API Reference
### Operator endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/operator/register` | POST | Create operator account |
| `/api/v1/operator/profile` | GET | View profile and API keys |
| `/api/v1/operator/stats` | GET | Revenue and usage stats |
### Server management
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/servers` | POST | Register an MCP server |
| `/api/v1/servers` | GET | List your servers |
| `/api/v1/servers/{id}/plans` | POST | Create pricing plan |
### Proxy
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/proxy/{slug}/*` | ANY | Proxied calls with billing enforcement |
| `/mcp/` | ANY | Streamable HTTP MCP transport |
## Architecture
```
┌─────────────┐ ┌──────────────────────┐ ┌──────────────────┐
│ AI Agent / │────▶│ MCP Billing Gateway │────▶│ Your MCP Server │
│ MCP Client │◀────│ (hosted on Railway) │◀────│ (upstream) │
└─────────────┘ └──────────────────────┘ └──────────────────┘
│
├── Payment verification (Stripe / x402)
├── Usage tracking & rate limiting
├── Tier enforcement
└── Operator dashboard
```
The gateway is a transparent proxy. Callers interact with your MCP server normally — the gateway intercepts requests, verifies payment, tracks usage, and forwards to your upstream server.
## Self-hosted
The gateway is open for use at the hosted URL above. For self-hosted deployments, clone the server repository and deploy via Docker:
```bash
docker build -t mcp-billing-gateway .
docker run -p 3000:3000 mcp-billing-gateway
```
## License
[MIT](LICENSE)
<!-- mcp-name: io.github.sapph1re/mcp-billing-gateway -->