MCP-Server

@paymos/mcp ist ein lokaler Server nach dem Model Context Protocol. Ihr Coding-Agent erhält sechs Paymos-Werkzeuge und die Entwicklerdokumentation als Ressourcen und baut die Integration danach selbst: Er legt Sandbox-Rechnungen an, öffnet die Zahlungsseite, simuliert eine Zahlung, verfolgt den Status bis paid, prüft eine Webhook-Signatur und schreibt den Produktionscode auf Basis eines Server-SDKs.

Der Server spricht stdio und öffnet keine Netzwerk-Ports: Er ruft die Händler-API über das offizielle SDK mit Ihrem Testschlüsselpaar auf. Setup gibt keine Secret-Werte aus. Wie Ihr Client und Modell Daten protokollieren, hängt von deren Einstellungen ab.

Voraussetzungen

• Node.js 20 oder neuer
• Ein Testschlüsselpaar aus Dashboard → Entwickler → API-Schlüssel: eine pk_test_-Schlüssel-ID und ein sk_test_-Secret

MCP-Client einrichten

npx -y @paymos/mcp setup

Wählen Sie den Client und geben Sie Ihr Testschlüsselpaar ein. Die Eingabe des Secrets bleibt verborgen. Optional können Sie ein Webhook-Secret für die Signaturprüfung hinterlegen. Nach dem Speichern starten Sie den Client neu oder verbinden den MCP-Server erneut; anschließend stehen die Paymos-Werkzeuge in der Sitzung bereit.

Mit --client wählen Sie den Client direkt:

npx -y @paymos/mcp setup --client codex

Client	Wert für --client	Standarddatei
Codex	codex	$CODEX_HOME/config.toml oder ~/.codex/config.toml
Claude Code	claude-code	~/.claude.json
Claude Desktop	claude-desktop	claude_desktop_config.json im Claude-Benutzerordner unter Windows/macOS
Kimi CLI	kimi	$KIMI_CODE_HOME/mcp.json oder ~/.kimi-code/mcp.json
Cursor	cursor	~/.cursor/mcp.json
Windsurf	windsurf	~/.codeium/windsurf/mcp_config.json
OpenCode	opencode	OPENCODE_CONFIG oder $XDG_CONFIG_HOME/opencode/ (sonst ~/.config/opencode/)
VS Code	vscode	.vscode/mcp.json im aktuellen Verzeichnis
Andere Clients	generic	Pfad mit --config angeben

OpenCode verwendet eine vorhandene opencode.jsonc, sonst opencode.json. Für Cline, Roo Code und eigene MCP-Clients nehmen Sie generic und den tatsächlichen Dateipfad aus den Client-Einstellungen:

npx -y @paymos/mcp setup --client generic --config /pfad/zum/mcp-config.json

Mit --config PATH überschreiben Sie auch bei anderen Clients den Standardpfad. Claude Desktop benötigt diese Angabe außerhalb von Windows und macOS. --credentials-file PATH legt fest, wo das Schlüsselpaar gespeichert wird. --dry-run zeigt die geplanten Änderungen, ohne Dateien zu schreiben oder Secrets auszugeben; --help erklärt die Optionen.

Schlüssel separat speichern

Setup speichert die Schlüssel unter $XDG_CONFIG_HOME/paymos/mcp/credentials.json; ohne XDG_CONFIG_HOME gilt ~/.config/paymos/mcp/credentials.json. Im Client-Config steht nur PAYMOS_CREDENTIALS_FILE mit diesem Pfad. Eine Datei außerhalb des Projekts hält das Schlüsselpaar aus dessen Konfiguration heraus.

Für einen Ablauf ohne Eingabedialog setzen Sie PAYMOS_API_KEY_ID und PAYMOS_API_SECRET in der Umgebung; PAYMOS_WEBHOOK_SECRET ist optional. Die bisherigen Umgebungsvariablen und Server-Flags --api-key-id und --api-secret funktionieren weiter. Beim Serverstart gilt pro Feld die Reihenfolge Umgebung, Flags, Schlüsseldatei.

Vorhandene Server, Kommentare und Modelleinstellungen bleiben erhalten. Derselbe Aufruf mit denselben Daten ergänzt keinen zweiten Eintrag. Bei einem widersprüchlichen Paymos-Eintrag oder anderen Schlüsseln in der Zieldatei bricht Setup ab. Prüfen Sie dann die bestehende Datei und wählen Sie bei Bedarf einen anderen Pfad.

Modelle im gewählten Client verwenden

Der Client stellt die MCP-Verbindung her. Das gilt für Codex und Kimi CLI ebenso wie für OpenCode, GLM in Claude Code oder ein eigenes Modell: Das Modell muss Werkzeugaufrufe unterstützen. Setup ergänzt den Paymos-Server; Ihren Modellnamen und API-Endpunkt wählen Sie weiterhin im Client.

Manuell eintragen

Sie können den Server auch selbst eintragen. Legen Sie zuerst eine separate Schlüsseldatei an:

{"apiKeyId":"pk_test_…","apiSecret":"sk_test_…","webhookSecret":"whsec_…"}

Unter Unix beschränken Sie den Zugriff auf Ihren Benutzer:

chmod 600 /absoluter/pfad/credentials.json

Der Server lehnt Dateien ab, die andere Benutzer oder Gruppen lesen können. Unter Windows gelten die vorhandenen Zugriffsrechte Ihres Benutzerordners. Lassen Sie webhookSecret weg, wenn Sie keine Signaturen prüfen. Ersetzen Sie /absoluter/pfad/credentials.json in den folgenden Beispielen durch Ihren Dateipfad.

Clients mit mcpServers

Clients mit mcpServers, etwa Claude Code, Cursor oder Kimi CLI, verwenden diesen Aufbau:

{"mcpServers":{"paymos":{"command":"npx","args":["-y","@paymos/mcp"],"env":{"PAYMOS_CREDENTIALS_FILE":"/absoluter/pfad/credentials.json"}}}}

Codex

Codex verwendet TOML:

[mcp_servers.paymos]
command = "npx"
args = ["-y", "@paymos/mcp"]
[mcp_servers.paymos.env]
PAYMOS_CREDENTIALS_FILE = "/absoluter/pfad/credentials.json"

OpenCode

OpenCode führt den Startbefehl als Array unter mcp:

{"mcp":{"paymos":{"type":"local","command":["npx","-y","@paymos/mcp"],"environment":{"PAYMOS_CREDENTIALS_FILE":"/absoluter/pfad/credentials.json"},"enabled":true}}}

VS Code

VS Code verwendet servers und type: "stdio":

{"servers":{"paymos":{"type":"stdio","command":"npx","args":["-y","@paymos/mcp"],"env":{"PAYMOS_CREDENTIALS_FILE":"/absoluter/pfad/credentials.json"}}}}

Zed

Zed richten Sie manuell unter context_servers ein. Die globale Datei unter Unix ist ~/.config/zed/settings.json; .zed/settings.json gehört zum Projekt. Unter Windows öffnen Sie die tatsächliche settings.json über die Zed-Einstellungen. Einen Setup-Adapter für Zed gibt es nicht.

Startbefehl unter Windows

Unter Windows lautet der Befehl cmd, die Argumente sind ["/d","/c","npx","-y","@paymos/mcp"]. In OpenCode beginnt das command-Array entsprechend mit "cmd".

Was der Agent kann

Werkzeug	Zweck
create_invoice	Legt eine Sandbox-Rechnung an; idempotent je external_order_id; liefert payment_url
get_invoice	Liest den aktuellen Rechnungsstatus
list_invoices	Liest eine Cursor-Seite Rechnungen mit Filtern
cancel_invoice	Storniert eine unbezahlte Rechnung mit gespeichertem Grund
simulate_invoice_payment	Führt eine Rechnung durch paid, paid_late, overpaid, underpay oder cancel — nur Sandbox
verify_webhook_signature	Prüft einen X-Webhook-Signature-Header lokal, ohne API-Aufruf

Fünf Dokumentationsseiten liegen als Ressourcen bei, sodass der Agent sie in der Sitzung liest, statt im Netz zu suchen: paymos://docs/quick-start, paymos://docs/hosted-checkout, paymos://docs/webhooks, paymos://docs/testing-sandbox, paymos://docs/server-sdks.

Die vorhandenen Werkzeugnamen und Schemata bleiben mit diesem Setup erhalten; paid_late ergänzt die Simulation.

Nur Sandbox

Der Server akzeptiert ausschließlich Testschlüsselpaare. Live- (pk_live_ / sk_live_) und Auszahlungsschlüssel (rk_…) werden beim Start und bei jedem Aufruf mit einer klaren Fehlermeldung abgelehnt. Sobald der Agent Ihre Integration geschrieben und geprüft hat, geht Ihr eigener Code mit den Live-Schlüsseln in Produktion — der MCP-Server bleibt außerhalb des Produktionspfads.

Der gehostete MCP-Server ist auf Phase 2 verschoben und derzeit nicht verfügbar. Ein Veröffentlichungstermin steht nicht fest.

Nächste Schritte

• Schnellstart — der Ablauf, den der Agent automatisiert, einmal von Hand durchgespielt
• Testen in der Sandbox — was die Simulation abdeckt
• Server-SDKs — was der generierte Code aufruft
• Webhooks — Ereignisse, Wiederholungen und Signaturprüfung