Add API key auth, credit billing, rate limiting, analytics, and 199+ production endpoints to any Model Context Protocol server. Zero config. No code changes. No dependencies.
npx paygate-mcp wrap --server "your-mcp-server"
PayGate sits between agents and your server. Your server code stays untouched.
Without PayGate: build API key management, credit tracking, per-tool pricing, spending limits, refund logic, and Stripe integration from scratch.
Without PayGate: instrument every tool call, build time-series analytics, create usage dashboards, export reports, and track denial reasons.
Without PayGate: implement rate limiting, IP restrictions, tool-level ACL, spending caps, key expiry, SSRF prevention, and input validation.
PayGate adds all of this with one command. No code changes to your server.
npx paygate-mcp wrap \
--server "npx @modelcontextprotocol/server-filesystem /tmp" \
--price 2 \
--rate-limit 30curl -X POST http://localhost:3402/keys \
-H "Content-Type: application/json" \
-H "X-Admin-Key: YOUR_ADMIN_KEY" \
-d '{"name": "my-client", "credits": 100}'curl -X POST http://localhost:3402/mcp \
-H "Content-Type: application/json" \
-H "X-API-Key: pg_a1b2c3..." \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"read_file",
"arguments":{"path":"/tmp/data.txt"}}}'
# Response includes: X-Credits-Remaining: 98Configure a Stripe webhook to auto-top-up credits when customers pay. PayGate handles the rest.
Observe every tool call without charging. See real usage patterns, test your pricing model, validate rate limits — then flip to enforcement when you're ready.
--shadow-mode flag or "shadowMode": true in config. Switch to live billing without restarting.
Set global or per-tool prices in credits. Integer-only to prevent float exploits. Dynamic pricing per KB of input. Spending limits per key. Automatic refunds when downstream calls fail.
Full authorization server. Dynamic client registration (RFC 7591), token refresh and revocation (RFC 7009), client_credentials grant for M2M auth, server metadata discovery.
/metrics in standard Prometheus text format. Tool calls, credits, denials, rate limits, active keys, sessions, uptime. Plug into Grafana or Datadog.
Wrap N MCP servers behind one PayGate instance. Tools prefixed by server name — fs:read_file, github:search. Shared credits across all backends.
Run multiple PayGate instances behind a load balancer. Atomic credit deduction via Lua scripts, distributed rate limiting, token revocation sync. Zero-dep RESP client.
Full MCP Streamable HTTP transport. POST returns JSON or SSE, GET opens notification streams, DELETE terminates sessions. Auto-expiry, keepalive, and session limits.
AI agents discover pricing via /.well-known/mcp-payment and /pricing. Standard -32402 error code for payment-required. tools/list includes _pricing metadata.
66+ enterprise features across 8 categories. Click to expand.
Complete key lifecycle: create with credits, ACL, quotas, expiry, spending limits, and IP allowlists in one request. Rotate keys preserving all state. Self-service key rotation via portal with 5-minute rate limiting that survives across rotations. Suspend/resume without permanent revocation. Clone keys for quick provisioning. Assign human-readable aliases. Attach metadata tags for external systems. Add timestamped admin notes. Schedule future actions (topup, suspend, revoke). Bulk operations for multi-key management. Key templates for reusable presets. Import/export with conflict resolution.
64+ analytics endpoints. Time-series data with hourly/daily bucketing. Tool breakdown by calls, credits, latency (p95/p99), and error rates. Consumer segmentation (power/regular/casual/dormant). Revenue analysis per tool, key, namespace, and group. Credit burn rate forecasting with depletion estimates. Capacity planning with utilization metrics. Anomaly detection with severity ratings. SLA monitoring with per-tool availability. Consumer retention cohorts. Cost analysis with trend comparison. Traffic analysis with peak usage identification. Compliance audit export — framework-specific reports for SOC 2, GDPR, and HIPAA with event classification, severity levels, and JSON/CSV export.
Per-tool pricing with global defaults. Dynamic pricing per KB of input (creditsPerKbInput). Spending limits per key to cap lifetime spend. Credit transfers between keys with atomic deduction. Credit reservations for pending operations (configurable TTL, max 50 per key). Auto-topup when balance drops below threshold with daily caps. Complete credit ledger history (allocation, topup, transfer, spent, refunded). Refund on failure when downstream tool calls error. Stripe Checkout — self-service credit purchases via Stripe Checkout Sessions with configurable packages and auto-topup. Credit packages listing — public endpoint for available packages with pricing. Credit history — full mutation history with spending velocity (credits/hour, credits/day, calls/day) and depletion forecast. Usage alerts — self-service low-credit threshold alerts with HTTPS webhook notifications. Outcome-based pricing — charge extra credits based on response output size with creditsPerKbOutput per-tool config, X-Output-Surcharge header. Budget policies — governance engine with daily/monthly budget caps per key, namespace, or tool, burn rate monitoring, progressive throttling actions (warn/throttle/block), depletion forecasts, and admin CRUD via /admin/budget-policies. Quota management — granular daily/weekly/monthly hard caps per API key with per-tool or global scope, calls or credits metric, burst allowance (temporary over-limit percentage), three overage actions (deny/warn/throttle), UTC-based period boundaries with automatic rollover, manage via /admin/quota-rules.
Per-tool ACL with whitelist and blacklist per key. IP allowlisting with IPv4 and CIDR range support (up to 200 per key). IP country restrictions (geo-fencing) with per-key allow/deny country lists (ISO 3166-1 alpha-2). Content guardrails with PII detection and redaction — 8 built-in rules (credit card, SSN, email, phone, AWS key, API secret, IBAN, passport), 4 actions (log/warn/block/redact), violation tracking. Scoped tokens (pgt_ prefix) with HMAC-SHA256 signing, zero server-side state, and max 24h TTL. Token revocation with O(1) fingerprint lookup and Redis cross-instance sync. Admin RBAC with three roles: super_admin, admin, viewer. Bootstrap key rotation without restart. Request body size limits (1 MB). Content-Type enforcement. Admin rate limiting per IP. Session creation rate limiting. IP access control with CIDR allow/deny lists, per-key IP binding, auto-blocking after configurable violation thresholds, X-Forwarded-For trusted proxy depth. HMAC-SHA256 request signing with replay protection via timestamp tolerance and nonce tracking — per-key signing secrets with rotation, timing-safe comparison. Multi-tenant isolation with per-tenant rate limits, credit pools, usage tracking, API key binding, tenant suspension/activation — full data boundary enforcement for platform operators.
Team management with shared budgets, quotas, and usage tracking. Per-member breakdown with gate-level enforcement. Multi-tenant namespaces for data isolation — keys, usage, and analytics filtered by tenant. Namespace-level stats and comparison. Key groups with reusable policy templates: shared ACL, rate limits, pricing overrides, IP allowlists, and quotas applied to groups of keys. Key-level overrides for individual exceptions.
HMAC-SHA256 signed webhook payloads with timing-safe verification and replay protection. Batched delivery (10 events/batch, 5s flush). Exponential backoff retry with dead-letter queue. Webhook filter rules to route events by type and key prefix to different destinations — each with independent secrets and retry queues. Webhook test endpoint, delivery log, pause/resume for maintenance, and health overview. Per-key webhook URLs — key-level webhook routing with SSRF protection, HMAC-SHA256 signing, and lazy emitter management. Webhook replay (DLQ) — dead letter queue management for failed webhook deliveries with replay (single/bulk), status tracking (pending/retrying/succeeded/exhausted), configurable max retries with timeout, purge by ID or status, age-based expiry, manage via /admin/webhook-replay.
Config hot reload (POST /config/reload) without restart — update pricing, rate limits, and feature flags live. Config validation and dry-run mode that discovers tools and prints a pricing table before starting. Maintenance mode pauses /mcp while keeping admin endpoints live. Scheduled actions for future topup/suspend/revoke. Import/export keys as JSON or CSV. Health check endpoint with status, uptime, in-flight count, and Redis/webhook stats. Graceful shutdown with in-flight request drain. State backup — full server state export as versioned JSON with SHA-256 checksum verification and Content-Disposition header for download. State restore — import from backup with merge, overwrite, or full replacement modes and per-entity results. API version header — X-PayGate-Version on every HTTP response for client version tracking. Response caching — SHA-256 keyed cache with LRU eviction, per-tool TTL, X-Cache: HIT/MISS header, admin management via /admin/cache. Circuit breaker — three-state (closed/open/half_open) backend failure detection with auto-recovery, admin reset via /admin/circuit. Configurable timeouts — per-tool and global timeout for tool calls with error code -32004. Concurrency limiter — per-key and per-tool inflight request caps (distinct from rate limiting), error code -32005 with Retry-After header, runtime-adjustable via /admin/concurrency. Traffic mirroring — fire-and-forget request duplication to a shadow backend for A/B testing MCP server versions, percentage-based sampling, configurable timeout, admin management via /admin/mirror. Tool aliasing — rename tools with RFC 8594 Deprecation, Sunset, and Link headers, chain prevention, per-alias call counts, CRUD via /admin/tool-aliases. Usage plans — tiered key policies (free/pro/enterprise) bundling rate limits, quotas, credit multipliers, and tool ACL into reusable templates, assign keys to plans via /admin/keys/plan, denied tools rejected with error code -32403. Tool input schema validation — per-tool JSON Schema validation at the gateway, zero-dependency validator supporting type/required/enum/minLength/pattern/items, error code -32602 with detailed error list, manage via /admin/tools/schema. Canary routing — weighted traffic splitting between primary and canary MCP servers for zero-downtime upgrades, percentage-based routing (0-100%), crypto.randomInt for unbiased decisions, per-backend call/error tracking, manage via /admin/canary. Request/response transforms — declarative rewriting of tool call arguments and responses with set/remove/rename/template operations, wildcard tool matching, priority ordering, deep clone on apply, import/export, manage via /admin/transforms. Backend retry policy — automatic retry with exponential backoff and jitter for transient failures, configurable retry budget (max % of traffic as retries with cold-start grace), retryable error pattern matching, per-tool stats, manage via /admin/retry-policy. Adaptive rate limiting — dynamic rate adjustment based on per-key behavior analysis, auto-tightens for high error rates, auto-boosts for good actors, cooldown periods, LRU eviction, batch evaluation, manage via /admin/adaptive-rates. Request deduplication — idempotency layer preventing duplicate billing from agent retries, X-Idempotency-Key header with SHA-256 auto-generation fallback, in-flight request coalescing, configurable TTL window, LRU eviction, credits-saved tracking, manage via /admin/dedup. Priority queue — tiered request prioritization (critical/high/normal/low/background) with fair scheduling, per-key priority assignment, configurable max wait times per tier, starvation prevention via automatic promotion, manage via /admin/priority-queue. Cost allocation tags — per-request cost attribution via X-Cost-Tags header (JSON), aggregated chargeback reports by any dimension, cross-tabulation, CSV export for billing/ERP integration, required tag enforcement per key, cardinality limits, manage via /admin/cost-tags. Tool dependency graph — DAG-based workflow validation for multi-step agent pipelines, dependency registration with hard/soft modes, execution order enforcement, topological sort with cycle detection, failure propagation (upstream failure blocks downstream), transitive prerequisite/dependent analysis, manage via /admin/tool-deps. Config profiles — named configuration presets with save/activate/rollback, profile inheritance chains (base → child merging), SHA-256 checksums, flat-key diffing for comparison (onlyInA/onlyInB/changed/unchanged), import/export as JSON with merge or replace mode, activation history, circular inheritance detection, manage via /admin/config-profiles. Scheduled reports — automated periodic usage, billing, compliance, and security reports delivered via webhook with daily/weekly/monthly frequency, HMAC-SHA256 signed payloads, namespace/group/tool/key filters, manage via /admin/scheduled-reports. Approval workflows — pre-execution approval gates for high-cost or sensitive tool calls with three conditions (cost_threshold, tool_match, key_match), pending requests with configurable TTL, approve/deny/expire lifecycle, manage via /admin/approval-workflows. Gateway hooks — request lifecycle hooks at three stages (pre_gate, pre_backend, post_backend) with four types (log, header_inject, metadata_tag, reject), priority-based execution, tool/key glob filtering, manage via /admin/gateway-hooks.
Prometheus-compatible /metrics with cardinality caps and output size limits. Structured logging with configurable levels (debug/info/warn/error/silent) and formats (text/json). Admin event stream via SSE for real-time audit events. Request log ring buffer (5,000 entries) with queryable history — filter by tool, key, status, and time range. Export as JSON or CSV. OpenAPI 3.1 spec at /openapi.json covering all 199+ endpoints. Interactive Swagger UI docs at /docs. MCP Server Identity card at /.well-known/mcp.json for agent registries and automated discovery. Request tracing with structured spans at gate, backend, and transform stages — timing breakdown, P95 latency tracking, configurable sample rate, and JSON export via /admin/tracing.
70+ red-team security tests. Every attack vector covered.
RFC 1918 blocking on webhook URLs. Loopback, link-local, cloud metadata, IPv6 private ranges. DNS rebinding defense at delivery time.
safeJsonParse() strips __proto__, constructor, and prototype keys from all untrusted JSON input.
crypto.timingSafeEqual() on all key comparisons. Prevents timing side-channel attacks on authentication.
1 MB limit on all request bodies. 413 response for oversized. Prevents memory exhaustion from large payloads.
Strict envelope validation: jsonrpc field, method type, id type checking. Rejects malformed requests before processing.
RFC 7230 token validation on header names. CRLF/NUL stripping on values. 8 KB value cap. Custom headers validated at startup.
Per-IP sliding window on admin endpoints (120 req/min default). Session creation limits (60/min). Brute-force protection.
Per-IP rate limiting on /health, /info, /pricing, /docs, /openapi.json, /.well-known/*, /robots.txt (300 req/min default, configurable). 429 + Retry-After.
512-char cap on state parameters. Control character stripping. Error description capping in redirects.
NaN/Infinity rejection on all numeric fields. One billion cap per operation. Array bounds enforcement on ACL and IP lists.
X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy, CSP, Cache-Control on every response. X-Powered-By removed.
PII detection and redaction on inputs/outputs. Credit cards, SSN, emails, AWS keys, IBAN, passports. Block, warn, redact, or log actions.
Per-key country allow/deny lists. ISO 3166-1 alpha-2 codes via reverse-proxy headers (X-Country, CF-IPCountry). Zero-dependency.
| PayGate | MCPay | x402-mcp | Moesif | DIY | |
|---|---|---|---|---|---|
| Payment Model | Credits (fiat) | USDC (crypto) | Crypto | SaaS metering | Custom |
| Setup Time | 1 command | Wallet setup | Wallet setup | SDK integration | Weeks |
| Self-Hosted | Yes | Yes | Yes | No | Yes |
| Open Source | MIT | MIT | MIT | No | -- |
| Blockchain Required | None | Yes | Yes | No | No |
| SaaS Dependency | None | None | None | Required | None |
| Test Coverage | 5,924 tests | -- | -- | -- | 0 |
| Endpoints | 199+ | ~10 | ~5 | N/A | 0 |
| Shadow Mode | Yes | No | No | No | No |
| Analytics | 64+ endpoints | No | No | Yes | No |
| OAuth 2.1 | Full + M2M | No | No | -- | No |
| x402 Compat | Yes | Native | Native | No | No |
199+ endpoints organized by domain.
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/mcp | POST | X-API-Key | JSON-RPC 2.0 proxy (returns JSON or SSE) |
/mcp | GET | X-API-Key | SSE notification stream (Streamable HTTP) |
/mcp | DELETE | X-API-Key | Terminate SSE session |
/health | GET | None | Health check with status and uptime |
/info | GET | None | Server capabilities and feature flags |
/pricing | GET | None | Full per-tool pricing breakdown |
/metrics | GET | None | Prometheus metrics (counters, gauges, uptime) |
/dashboard | GET | In-browser | Admin web UI with real-time charts |
/openapi.json | GET | None | OpenAPI 3.1 spec (all 199+ endpoints) |
/docs | GET | None | Interactive Swagger UI API docs |
/.well-known/mcp.json | GET | None | MCP Server Identity (agent discovery) |
/robots.txt | GET | None | Crawler directives (allow public, disallow admin) |
/portal | GET | None | Self-service API key portal (browser UI) |
/portal/rotate | POST | X-API-Key | Self-service key rotation (rate limited) |
/ready | GET | None | Readiness probe (200/503 for k8s) |
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/keys | POST | X-Admin-Key | Create key with credits, ACL, quotas, expiry |
/keys | GET | X-Admin-Key | List keys (paginated, sortable, filterable) |
/keys/rotate | POST | X-Admin-Key | Rotate key preserving credits/ACL/quotas |
/keys/revoke | POST | X-Admin-Key | Permanently revoke an API key |
/keys/suspend | POST | X-Admin-Key | Temporarily suspend (can resume later) |
/keys/resume | POST | X-Admin-Key | Resume a suspended key |
/keys/acl | POST | X-Admin-Key | Set tool ACL (whitelist/blacklist) |
/keys/expiry | POST | X-Admin-Key | Set or remove key expiry TTL |
/keys/webhook | POST GET DELETE | X-Admin-Key | Per-key webhook URL (CRUD with SSRF protection) |
/keys/geo | POST GET DELETE | X-Admin-Key | Per-key country restrictions (allow/deny lists, ISO 3166-1) |
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/topup | POST | X-Admin-Key | Add credits to an existing key |
/balance | GET | X-API-Key | Client self-service balance check |
/limits | POST | X-Admin-Key | Set spending limit on a key |
/keys/transfer | POST | X-Admin-Key | Transfer credits between keys |
/keys/reserve | POST | X-Admin-Key | Reserve credits for pending operations |
/usage | GET | X-Admin-Key | Export usage data (JSON/CSV) |
/stripe/webhook | POST | Stripe sig | Auto-topup on Stripe payment |
/balance/history | GET | X-API-Key | Credit mutation history with spending velocity |
/balance/alerts | GET POST DELETE | X-API-Key | Self-service low-credit usage alerts |
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/oauth/register | POST | None | Dynamic client registration (RFC 7591) |
/oauth/authorize | GET | Admin | Authorization code with PKCE (S256) |
/oauth/token | POST | Client | Token exchange and refresh |
/oauth/revoke | POST | Client | Token revocation (RFC 7009) |
/.well-known/oauth-authorization-server | GET | None | OAuth server metadata discovery |
/.well-known/mcp-payment | GET | None | MCP payment metadata (SEP-2007) |
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/admin/analytics/overview | GET | X-Admin-Key | System-wide dashboard metrics |
/admin/analytics/tools/* | GET | X-Admin-Key | Tool stats, latency, error rates, correlation |
/admin/analytics/consumers/* | GET | X-Admin-Key | Consumer insights, segmentation, LTV, churn |
/admin/analytics/revenue/* | GET | X-Admin-Key | Revenue analysis, forecasting, profitability |
/admin/analytics/traffic/* | GET | X-Admin-Key | Request volume, trends, peak usage times |
/admin/analytics/denials/* | GET | X-Admin-Key | Denial analysis by reason, key, tool, time |
64+ analytics endpoints total. View full API docs
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/status | GET | X-Admin-Key | Full dashboard with all usage stats |
/audit | GET | X-Admin-Key | Query audit log (type, actor, time range) |
/audit/export | GET | X-Admin-Key | Export audit log (JSON or CSV) |
/requests | GET | X-Admin-Key | Queryable request log (5,000 entries) |
/config | GET | X-Admin-Key | Current config (secrets masked) |
/config/reload | POST | X-Admin-Key | Hot reload config without restart |
/admin/cache | GET DELETE | X-Admin-Key | Response cache stats and clear |
/admin/circuit | GET POST | X-Admin-Key | Circuit breaker status and reset |
/admin/compliance/export | GET | X-Admin-Key | Compliance audit export (SOC 2/GDPR/HIPAA) |
/admin/guardrails | GET POST DELETE | X-Admin-Key | Content guardrails (PII detection rules, toggle, import) |
/admin/guardrails/violations | GET DELETE | X-Admin-Key | Guardrail violation history (query, clear) |
/admin/concurrency | GET POST | X-Admin-Key | Inflight request counts per key/tool, update limits |
/admin/mirror | GET POST DELETE | X-Admin-Key | Traffic mirroring (configure shadow backend, stats) |
/admin/tool-aliases | GET POST DELETE | X-Admin-Key | Tool aliasing with RFC 8594 deprecation headers |
/admin/plans | GET POST DELETE | X-Admin-Key | Usage plans (tiered key policies with rate/credit/tool limits) |
/admin/keys/plan | POST | X-Admin-Key | Assign/unassign key to usage plan |
/admin/tools/schema | GET POST DELETE | X-Admin-Key | Per-tool JSON Schema validation (register, list, remove) |
/admin/canary | GET POST DELETE | X-Admin-Key | Canary routing (weighted traffic splitting between backends) |
/admin/transforms | GET POST PUT DELETE | X-Admin-Key | Request/response transform pipeline (declarative rewriting rules) |
/admin/retry-policy | GET POST | X-Admin-Key | Backend retry policy (exponential backoff, budget, stats) |
/admin/adaptive-rates | GET POST | X-Admin-Key | Adaptive rate limiting (behavior-based dynamic adjustment) |
/admin/dedup | GET POST DELETE | X-Admin-Key | Request deduplication (idempotency layer, credits-saved tracking) |
/admin/priority-queue | GET POST | X-Admin-Key | Priority queue (5-tier fair scheduling, key priority assignment) |
/admin/cost-tags | GET POST DELETE | X-Admin-Key | Cost allocation tags (chargeback reports, CSV export, required tags) |
/admin/ip-access | GET POST DELETE | X-Admin-Key | IP access control (CIDR allow/deny, per-key IP binding, auto-blocking) |
/admin/signing | GET POST DELETE | X-Admin-Key | Request signing (HMAC-SHA256 secrets, rotation, replay protection) |
/admin/tenants | GET POST DELETE | X-Admin-Key | Multi-tenant isolation (tenant CRUD, key binding, credit pools, suspension) |
/admin/tracing | GET POST DELETE | X-Admin-Key | Request tracing (structured spans, timing breakdown, P95 tracking, export) |
/admin/budget-policies | GET POST DELETE | X-Admin-Key | Budget policies (daily/monthly caps, burn rate monitoring, throttle actions) |
/admin/tool-deps | GET POST DELETE | X-Admin-Key | Tool dependency graph (DAG validation, topological sort, failure propagation) |
/admin/quota-rules | GET POST DELETE | X-Admin-Key | Quota management (daily/weekly/monthly caps, per-tool granularity, burst allowance) |
/admin/webhook-replay | GET POST DELETE | X-Admin-Key | Webhook replay DLQ (dead letter management, bulk replay, status tracking) |
/admin/config-profiles | GET POST DELETE | X-Admin-Key | Config profiles (named presets, inheritance, diff/rollback, import/export) |
/admin/scheduled-reports | POST | X-Admin-Key | Scheduled reports (automated periodic reports via webhook) |
/admin/approval-workflows | POST | X-Admin-Key | Approval workflows (pre-execution gates for sensitive tool calls) |
/admin/gateway-hooks | POST | X-Admin-Key | Gateway hooks (lifecycle hooks at pre_gate/pre_backend/post_backend) |
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/webhooks/test | POST | X-Admin-Key | Test webhook delivery (synchronous) |
/webhooks/deliveries | GET | X-Admin-Key | Webhook delivery log with status/timing |
/webhooks/health | GET | X-Admin-Key | Webhook success rate and queue stats |
/webhooks/pause | POST | X-Admin-Key | Pause webhook delivery (buffer events) |
/webhooks/resume | POST | X-Admin-Key | Resume delivery and flush buffer |
/webhooks/filters | GET | X-Admin-Key | List event routing filter rules |
initialize, tools/list, resources/list, prompts/list, and ping pass through without auth or billing.
You built a useful MCP server. Now charge per tool call instead of giving it away. One command to add billing, rate limiting, and analytics.
Expose your API to AI agents via MCP. PayGate handles auth, billing, and abuse prevention. You focus on your service.
Track which teams use what tools and how much. Enforce usage limits. Manage access with API keys. Namespace isolation per tenant.
npm install paygate-mcp