> ## Documentation Index
> Fetch the complete documentation index at: https://docs.business-os.de/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Business OS als gehosteter MCP Server für claude.ai, Cursor, Windsurf und das Agent SDK

# MCP Server

Der **Hosted MCP Server** stellt Business OS — **Banking + DATEV** — als typisierte Tools für KI-Agenten bereit, die außerhalb der Shell laufen: **claude.ai**, **Cursor**, **Windsurf** und das **Agent SDK**. Er läuft remote (kein lokaler Prozess, keine Installation) und authentifiziert jede Sitzung per **OAuth 2.1**.

* **Remote & stateless** — funktioniert im Web, auf Mobile und in Cloud-Agenten
* **OAuth 2.1 + PKCE** — pro Nutzer-Sitzung eigene Autorisierung
* **Strukturierte Tool-Definitionen** mit JSON Schema
* **Voller Funktionsumfang** — Banking (PSD2) und DATEV (DUO, Rechnungswesen Lesen/Schreiben)

<Note>
  Für Claude **Code** (Shell vorhanden) ist die [CLI + Skill](/sdks/cli) der einfachere Weg — `business-os init` bringt Claude die Befehle bei. Der Hosted MCP ist für Agenten **ohne** Shell gedacht.
</Note>

## Setup

Der Server wird als **Custom Connector** eingebunden. Server-URL:

```
https://mcp.business-os.de
```

### claude.ai

1. **Einstellungen → Connectors → Custom Connector hinzufügen**
2. URL `https://mcp.business-os.de` eintragen und speichern
3. Beim ersten Verbinden öffnet sich die Business-OS-Autorisierungsseite — dort deinen **API Key** aus dem [Dashboard](https://app.business-os.de) einfügen und bestätigen
4. Die Tools stehen danach in jeder Unterhaltung zur Verfügung

### Cursor / Windsurf

In der MCP-Konfiguration einen Remote-Server mit derselben URL (`https://mcp.business-os.de`) eintragen; der OAuth-Flow läuft identisch im Browser.

<Note>
  Es wird **kein** API Key in eine lokale Datei geschrieben — die Autorisierung läuft über den Browser-OAuth-Flow, und jede Sitzung erhält ihr eigenes Token.
</Note>

## Verfügbare Tools

Nach dem Verbinden stehen folgende Tools im Agenten zur Verfügung.

### Banking AIS

| Tool                | Beschreibung                             |
| ------------------- | ---------------------------------------- |
| `list_connections`  | Alle Banking-Connections auflisten       |
| `get_connection`    | Einzelne Connection abrufen              |
| `delete_connection` | Connection löschen                       |
| `list_accounts`     | Konten auflisten (inkl. aktuellem Saldo) |
| `get_account`       | Einzelnes Konto abrufen                  |
| `list_balances`     | Tägliche Saldenreihe eines Kontos        |
| `list_transactions` | Transaktionen auflisten                  |

### Banking PIS

| Tool                     | Beschreibung                                |
| ------------------------ | ------------------------------------------- |
| `create_payment`         | SEPA-Zahlung initiieren                     |
| `list_payment_templates` | Payment-Templates + unterstützende Provider |
| `list_payments`          | Zahlungen auflisten                         |
| `get_payment`            | Zahlungsdetails abrufen                     |

### Banking — Sonstige

| Tool               | Beschreibung                 |
| ------------------ | ---------------------------- |
| `get_webhook_url`  | Aktuelle Webhook URL abrufen |
| `set_webhook_url`  | Webhook URL setzen           |
| `search_providers` | Banken nach Name suchen      |

### DATEV — Allgemein & Unternehmen Online (DUO)

| Tool                                                                          | Beschreibung                                   |
| ----------------------------------------------------------------------------- | ---------------------------------------------- |
| `list_datev_companies`                                                        | Mandanten einer Verbindung (liefert companyId) |
| `list_duo_connections`                                                        | DUO-Verbindungen auflisten                     |
| `list_duo_belegtypen` / `list_duo_kassenbuecher` / `list_duo_rechnungsordner` | DUO-Stammdaten lesen                           |
| `upload_duo_beleg`                                                            | Beleg in DUO bereitstellen                     |
| `create_duo_kassenbuch_einfach` / `create_duo_kassenbuch_advanced`            | Kassenbuch-Einträge anlegen                    |
| `create_duo_buchungsvorschlag`                                                | Buchungsvorschlag anlegen                      |

### DATEV Rechnungswesen — Schreiben

| Tool                                              | Beschreibung                                            |
| ------------------------------------------------- | ------------------------------------------------------- |
| `list_rewe_connections`                           | ReWe-Write-Verbindungen auflisten                       |
| `list_rewe_belegtypen` / `list_rewe_steuersaetze` | Stammdaten lesen                                        |
| `upload_rewe_beleg`                               | Beleg bereitstellen                                     |
| `create_rewe_personenkonto`                       | Personenkonto anlegen (RVO „Rechnungsdatenservice 1.0") |
| `create_rewe_buchung`                             | Buchung anlegen (RVO „Rechnungsdatenservice 1.0")       |

### DATEV Rechnungswesen — Lesen

| Tool                                                              | Beschreibung                                             |
| ----------------------------------------------------------------- | -------------------------------------------------------- |
| `list_rewe_read_connections`                                      | ReWe-Read-Verbindungen auflisten                         |
| `get_rewe_read_permissions`                                       | RVO-Rechte einer Verbindung prüfen                       |
| `list_rewe_read_geschaeftsjahre` / `get_rewe_read_geschaeftsjahr` | Geschäftsjahre                                           |
| `get_rewe_read_kontenplan`                                        | Kontenplan (Sachkonto-Nummern → Namen)                   |
| `get_rewe_read_susa`                                              | Summen-und-Salden (SuSa / BWA)                           |
| `get_rewe_read_buchungsdaten`                                     | Buchungsdaten (Journaleinträge)                          |
| `get_rewe_read_opos`                                              | Offene Posten (Mahnwesen, Forderungen/Verbindlichkeiten) |
| `get_rewe_read_zahlungsbedingungen`                               | Zahlungsbedingungen                                      |

## Beispiel-Interaktion

Nach der Konfiguration kannst du Claude direkt in natürlicher Sprache ansprechen:

```
User: Zeige mir alle Bankkonten der Musterbank

Claude: Nutzt list_connections → findet Musterbank (ID: 9182...)
        Nutzt list_accounts mit connection_id → zeigt 9 Konten mit IBANs und Salden

User: Wie hoch ist der Gesamtsaldo?

Claude: Berechnet aus den Account-Daten: 12.500,00 EUR

User: Überweise 500€ von DE89... an Mustermann GmbH, DE27...

Claude: Nutzt create_payment → gibt Widget-URL zurück
        "Bitte öffne diesen Link um die Zahlung per TAN zu autorisieren: ..."
```

## Tool-Parameter

### `create_payment`

```json theme={null}
{
  "provider_code": "musterbank_oauth_client_de",
  "template_identifier": "SEPA",
  "creditor_name": "Mustermann GmbH",
  "creditor_iban": "DE27100777770209299700",
  "debtor_iban": "DE89370400440532013000",
  "amount": "500.00",
  "end_to_end_id": "RE-2026-001",
  "currency_code": "EUR",
  "description": "Rechnung RE-2026-001",
  "custom_fields": {
    "invoice_id": "RE-2026-001"
  }
}
```

### `list_transactions`

```json theme={null}
{
  "connection_id": "9182736450918273645",
  "account_id": "8273645091827364509",
  "from_date": "2026-01-01",
  "to_date": "2026-03-24"
}
```

## CLI + Skill vs. Hosted MCP

Beide sprechen dasselbe API an — die Wahl hängt davon ab, **wo** der Agent läuft.

|                            | CLI + Skill                           | Hosted MCP                                      |
| -------------------------- | ------------------------------------- | ----------------------------------------------- |
| **Läuft**                  | lokal, in der Shell (Claude Code, CI) | remote (claude.ai, Cursor, Windsurf, Agent SDK) |
| **Setup**                  | `business-os init`                    | Custom Connector auf `mcp.business-os.de`       |
| **Auth**                   | API Key lokal / Env-Var               | OAuth 2.1 pro Sitzung (Browser)                 |
| **Wie der Agent es nutzt** | Bash-Tool (`business-os …`)           | typisierte MCP-Tools                            |
| **Empfohlen für**          | Terminal, Scripting, Claude Code      | Cloud-/Web-Agenten ohne Shell                   |

<Note>
  Beide Oberflächen sind unabhängige Clients desselben REST-API und decken denselben Funktionsumfang ab (Banking + DATEV) — keine wrappt die andere.
</Note>