# MCP-Server

> Verbinden Sie Claude Code, Cursor oder jeden MCP-Client mit einem lokalen Paymos-Server — der Agent baut und prüft die Integration in der Sandbox.

`@paymos/mcp` ist ein lokaler Server nach dem [Model Context Protocol](https://modelcontextprotocol.io). 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](/de/docs/server-sdks.md).

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**](/de/docs/api-keys.md):
  eine `pk_test_`-Schlüssel-ID und ein `sk_test_`-Secret

## MCP-Client einrichten

```sh
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:

```sh
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:

```sh
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:

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

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

```sh
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:

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

### Codex

Codex verwendet TOML:

```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`:

```json
{"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"`:

```json
{"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](/de/docs/testing.md) |
| `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](/de/docs/quick-start.md) — der Ablauf, den der Agent automatisiert, einmal von Hand durchgespielt
- [Testen in der Sandbox](/de/docs/testing.md) — was die Simulation abdeckt
- [Server-SDKs](/de/docs/server-sdks.md) — was der generierte Code aufruft
- [Webhooks](/de/docs/webhooks.md) — Ereignisse, Wiederholungen und Signaturprüfung