MCPay

MCPay sitzt zwischen einem KI-Agenten und einem MCP-Server. Der Agent erhält ein kurzlebiges Ausgabetoken, das an einen Server, eine feste Aktionsliste, exakte Preise, ein Budget, eine Ablaufzeit und einen Nonce-Bereich gebunden ist. Das Gateway überprüft diese Richtlinie, beansprucht die Nonce atomar, ruft das Upstream-Tool auf und zeichnet dann erfolgreich gelieferte 2xx-Nutzung in einer dauerhaften Outbox auf.

Kein Abonnement pro Tool. Kein Creator-API-Schlüssel im Agenten. Kein Gleitkomma-Geld.

Beta-Status: Das Repository führt eine geschlossene Beta ohne echtes Geld durch. Wallet-Aufladungen sind Test-Ledger-Guthaben; Stripe-Einzahlungen, Creator-Auszahlungen, KYC/AML, Streitfälle und Steuer-Workflows sind noch nicht enthalten.

1. Der Agent erstellt eine Ausgabesitzung, die durch ein reserviertes Wallet-Guthaben gedeckt ist.

2. MCPay signiert den exakten Server, die Aktionspreise, das Budget, die Ablaufzeit und den Nonce-Bereich.

3. Das Gateway verifiziert das Token und beansprucht die Nonce in PostgreSQL vor dem Versand.

4. Eine gelieferte 2xx-Antwort gelangt in die lokale bbolt-Outbox und wird asynchron abgerechnet.

Das Repository enthält eine Go-API, ein Gateway, einen Abrechnungs-Worker, PostgreSQL-Migrationen, ein Creator-Dashboard, JavaScript- und Python-SDKs, Browser-Tests und einen Docker-Compose-Beta-Stack. Echte Einzahlungen und Auszahlungen bleiben absichtlich deaktiviert.

Produkttour

Die Control Plane zeigt reserviertes Agentenbudget, Creator-Umsatz, Volumen bezahlter Aufrufe, lokale Autorisierungslatenz und aktuelle Abrechnungsaktivität.

Screenshots verwenden einen festen Dokumentationsdatensatz. Die Zahlen sind keine Produktionsmetriken.

Related MCP server: MCP Gateway

Warum MCPay existiert

Ein Agent, der zehn bezahlte Tools aufruft, sollte nicht zehn Abonnements, zehn Abrechnungs-SDKs und zehn langlebige Geheimnisse benötigen. Ein Creator sollte keine Reservierungslogik, Replay-Schutz, Preischecks, Belegspeicherung und Abrechnungs-Worker schreiben müssen, bevor er fünf Cent für web_search verlangt.

MCPay macht den Ausgabenvertrag vor der Ausführung explizit:

Wenn der Anspruch nicht zur aktiven Sitzung passt, stoppt das Gateway, bevor das Upstream die Anfrage sieht.

Vergleich

Checkout ist der einfache Teil. MCPay übernimmt begrenzte Autorisierung, Duplikatunterdrückung über Hosts hinweg, unveränderliche Preise, Widerrufsreihenfolge, dauerhafte Lieferung akzeptierter Nutzung und wiederholungssichere Abrechnung.

Anforderungspfad

sequenceDiagram
    participant A as Agent
    participant C as MCPay API
    participant G as MCPay Gateway
    participant P as PostgreSQL
    participant T as MCP Tool
    participant W as Settlement Worker

    A->>C: Create spend session
    C->>P: Reserve budget and store price snapshot
    C-->>A: Ed25519-signed spend token
    A->>G: tools/call + token + nonce
    G->>G: Verify issuer, server, action, price, expiry
    G->>P: Atomic nonce claim
    P-->>G: Active and unique
    G->>P: Mark nonce dispatched
    G->>T: Execute tool
    T-->>G: Result
    G-->>A: Result
    G->>G: Persist delivered 2xx usage in bbolt outbox
    G->>C: Upload usage batch
    C->>P: Insert idempotent usage record
    W->>P: Settle creator credit

Der Control-Plane-Aufruf erfolgt vor dem Versand, weil reiner Offline-Replay-Schutz zwei Gateway-Maschinen nicht koordinieren oder eine widerrufene Sitzung stoppen kann. Signaturprüfungen finden weiterhin lokal statt, sodass fehlerhafte oder nicht zulässige Token nie den Datenbank-Anspruch erreichen.

Sicherheitsmodell

MCPay nennt ein signiertes JWT nicht "verschlüsselt". Das ist es nicht. Ausgabetoken tragen lesbare Ansprüche und verwenden Ed25519-Signaturen, damit ein Gateway jede Änderung erkennen kann, ohne den Signaturschlüssel zu besitzen.

Was Verschlüsselung im Ruhezustand hier bedeutet

MCPay fügt keine anwendungsseitige Feldverschlüsselung zu Ledger-Zeilen hinzu. PostgreSQL-Anmeldedaten, Signaturschlüssel, Gateway-Geheimnisse und Backups gehören in deinen Secret-Manager und verschlüsselten Speicher; verwaltetes PostgreSQL oder verschlüsselte Host-Volumes sollten Datenbankdateien im Ruhezustand schützen. Diese Unterscheidung ist wichtig, weil die Behauptung "alles ist verschlüsselt" die tatsächliche Vertrauensgrenze verbergen würde.

Für eine Beta-Bereitstellung halte PostgreSQL und den Worker in einem privaten Netzwerk, beende öffentliches TLS an Caddy, mounte Geheimnisse zur Laufzeit, sichere vor Migrationen und committe niemals deploy/.env.beta.

Lokal ausführen

Voraussetzungen: Docker Engine mit Compose v2, Go 1.25+ für die Schlüsselerzeugung und 4 GB verfügbarer Speicher. Node.js 24 läuft im Dashboard-Build-Container.

cp deploy/.env.beta.example deploy/.env.beta
go run ./cmd/mcpay-keygen

Füge die generierten Ed25519-Werte in deploy/.env.beta ein, ersetze alle replace-*-Werte und starte dann den Stack:

docker compose --env-file deploy/.env.beta -f deploy/compose.beta.yml config
docker compose --env-file deploy/.env.beta -f deploy/compose.beta.yml build
docker compose --env-file deploy/.env.beta -f deploy/compose.beta.yml up -d
docker compose --env-file deploy/.env.beta -f deploy/compose.beta.yml ps

Öffne http://localhost:8080. Der Compose-Stack startet PostgreSQL, Migrationen, API, Worker, Dashboard, Caddy und internes TLS. Test-Aufladungen bleiben virtuelle Guthaben.

Überprüfe den laufenden Stack:

MCPAY_BETA_URL=http://localhost:8080 ./scripts/verify-central-beta.sh

PowerShell:

./scripts/verify-central-beta.ps1 -BaseUrl http://localhost:8080

Bereitstellungshinweise, Backups, DNS und die Vercel/Supabase-Option findest du in docs/central-beta-runbook.md und docs/beta-deployment.md.

Einen MCP-Server verbinden

Erstelle einen Server und eine Aktion im Creator Studio, stelle seine serverbezogene Gateway-Anmeldedaten aus und führe dann das Gateway aus dem Repository neben dem MCP-Prozess aus:

go run ./cmd/mcpay-gateway \
  --target https://your-mcp-server.example \
  --mcp-path /mcp \
  --server-id srv_example \
  --environment beta \
  --token-issuer mcpay.beta \
  --public-key "$MCPAY_PUBLIC_KEY" \
  --control-plane-api https://api.example/v1/gateway/servers/srv_example \
  --nonce-claim-api https://api.example/v1/gateway/nonces/claim \
  --usage-api https://api.example/v1/usage-records \
  --usage-api-token "$MCPAY_GATEWAY_API_TOKEN" \
  --state-file ./mcpay-gateway.db

Bezahlte Anfragen tragen zwei Header:

Authorization: Bearer <spend-token>
X-MCPay-Nonce: <nonce-within-the-signed-range>

Das Gateway entfernt beide Header, bevor es die Anfrage an das Upstream weiterleitet.

Einen Agenten verbinden

MCPayAgentClient erstellt kurzlebige Sitzungen und injiziert Zahlungs-Header nur in erlaubte HTTPS-Gateway-Origins:

import {
  FileAgentSessionCreationStore,
  MCPayAgentClient,
} from "@mcpay/sdk-js";

const paid = new MCPayAgentClient({
  apiBaseUrl: "https://pay.example.com/api/mcpay",
  accessToken: process.env.MCPAY_ACCESS_TOKEN!,
  walletId: process.env.MCPAY_WALLET_ID!,
  serverId: process.env.MCPAY_SERVER_ID!,
  reservedBudget: 50,
  gatewayOrigins: ["https://tools.example.com"],
  sessionCreationStore: new FileAgentSessionCreationStore(
    "./mcpay-agent-sessions.json",
  ),
});

const response = await paid.fetch("https://tools.example.com/mcp", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
      name: "web_search",
      arguments: { query: "payment rails for MCP" },
    },
  }),
});

Initialisierung und Tool-Erkennung laufen ohne Ausgabe-Header durch. Die Sitzungserstellung verwendet einen Idempotenzschlüssel, sodass eine verlorene Antwort das Budget nicht doppelt reserviert.

Direkte SDK-Wrapper

JavaScript- und Python-Wrapper existieren für Entwicklung und private Integrationen. Der Produktionsmodus lehnt flüchtige Nutzung ab; das dauerhafte Gateway bleibt der empfohlene Bereitstellungspfad, da es Nonce- und Nutzungsstatus über Prozessneustarts hinweg beibehält.

import { MCPayClient } from "@mcpay/sdk-js";

const mcpay = new MCPayClient({
  publicKey: process.env.MCPAY_PUBLIC_KEY!,
  issuer: process.env.MCPAY_TOKEN_ISSUER!,
  serverId: process.env.MCPAY_SERVER_ID!,
  environment: "development",
  allowVolatileUsage: true,
});

export const paidSearch = mcpay.tool({
  name: "web_search",
  priceMinor: 5,
  handler: async (query: string) => search(query),
});

import os

from mcpay import MCPayClient

mcpay = MCPayClient(
    public_key=os.environ["MCPAY_PUBLIC_KEY"],
    issuer=os.environ["MCPAY_TOKEN_ISSUER"],
    server_id=os.environ["MCPAY_SERVER_ID"],
    environment="development",
    allow_volatile_usage=True,
)

@mcpay.tool(name="web_search", price_minor=5)
async def search(query: str):
    return await run_search(query)

Verifizierung

Der Hauptzweig prüft Go, PostgreSQL-Integration, Migrationen, beide SDKs, Browsertests, Paket-Builds, Abhängigkeits-Audits und die Docker-Compose-Konfiguration.

go test ./...
go test -race ./...
go vet ./...
go build ./cmd/...
npm ci
npm audit --audit-level=high
npm run build
npm run test
python -m pip install build
python -m build packages/sdk-python
python -m unittest discover -s packages/sdk-python/tests

Für PostgreSQL-Tests setzen Sie MCPAY_TEST_DATABASE_URL auf eine wegwerfbare migrierte Datenbank. Die Tests leeren Anwendungstabellen; verwenden Sie niemals eine Produktionsdatenbank.

Führen Sie den Loopback-Autorisierungs-Benchmark aus mit:

go run ./cmd/mcpay-benchmark --samples 1000 --warmup 100

Er meldet rohe, lokale SDK- und Gateway-p50/p95/p99 auf Ihrer Maschine. Der Benchmark schließt Sitzungseinrichtung, zentrale Ledger-Schreibvorgänge und asynchronen Nutzungs-Upload aus, ist also keine Produktions-SLA.

Was heute ausgeliefert wird

MCPay ist bereit für eine kontrollierte Beta mit Testguthaben. Es ist nicht bereit, Kundengelder zu halten.

Repository-Übersicht

Lizenz

MCPay verwendet die Business Source License 1.1. BSL ist keine OSI-anerkannte Open-Source-Lizenz, gibt aber jedem Zugriff auf den Quellcode und erlaubt Kopieren, Modifizieren, Weiterverbreiten und nicht-kommerzielle Nutzung.

Der MCPay Additional Use Grant erlaubt interne Produktionsnutzung, wenn der Nutzer oder die Organisation in den letzten 12 Monaten einen aggregierten Bruttoumsatz von nicht mehr als 100.000 USD hat. Er erlaubt keinen gehosteten, verwalteten, eingebetteten oder White-Label-MCPay-Dienst für Dritte. Produktionsnutzung außerhalb dieses Grants erfordert eine kommerzielle Lizenz; öffnen Sie ein Issue im offiziellen Repository, um kommerzielle Bedingungen anzufragen.

Am 13. August 2030 wechselt diese Version zur Apache License 2.0. BSL wendet auch ihre Open-Source-Change-License am vierten Jahrestag der ersten öffentlichen BSL-Verteilung einer Version an, falls dieses Datum früher eintritt.

Lesen Sie LICENSE für die verbindlichen Bedingungen. Das Dashboard wird separat unter der MIT-Lizenz in apps/dashboard/LICENSE verteilt, einschließlich Namensnennung für seinen ursprünglichen Autor und MCPay-Änderungen. Lassen Sie die BSL-Parameter vor einem Start mit echtem Geld oder einer Finanzierungs-Due-Diligence von Rechtsberatern prüfen.

Sicherheitsforschung ist willkommen. Quellcode-Zugang ermöglicht Überprüfung; er beweist nicht die Abwesenheit von Schwachstellen, und BSL liefert die Software ohne Sicherheitsgewähr.