# KI-Werkzeuge über MCP anbinden > Nutzen Sie die Integrations-API von BatteryPass aus Claude Code, Cursor, VS Code und anderen MCP-Clients mit einem API-Schlüssel Ihrer Organisation. BatteryPass betreibt einen **Model-Context-Protocol-Server (MCP)** unter `https:///mcp`. Ein KI-Werkzeug, das MCP spricht, verbindet sich mit einem API-Schlüssel Ihrer Organisation und erhält für jede Operation der Integrations-API ein Werkzeug (Tool): Es kann Batteriemodelle, Einheiten, Werte und deren Vollständigkeit abfragen, Pässe und ihre Versionen lesen, dem Änderungsfeed folgen, BatteryPass-JSON, PDFs und QR-Codes exportieren und, mit der passenden Berechtigung, Zustandsdaten und Lebenszyklusereignisse melden oder Tabellenimporte zuordnen und prüfen. Nutzen Sie ihn, wenn ein Assistent Fragen zu Ihren Daten beantworten soll („Bei welchen Einheiten von Modell X fehlen noch Angaben?“) oder Zustandsmeldungen für Sie vorbereiten und senden soll. Für zeitgesteuerte Integrationen ohne Aufsicht rufen Sie die REST-API direkt auf; die Werkzeuge sind dieselben Operationen. > [!NOTE] > Der MCP-Server gehört zu jeder BatteryPass-Installation und braucht keinen zusätzlichen Dienst. Er nutzt den > Transport „Streamable HTTP“ (zustandslos, Protokollversion 2026-07-28; ältere Clients mit dem > `initialize`-Handshake funktionieren ebenfalls). ## Bevor Sie beginnen 1. **API-Schlüssel erstellen** Ein Eigentümer Ihrer Organisation öffnet **Einstellungen → API-Schlüssel** und erstellt einen Schlüssel für genau dieses Werkzeug. Wählen Sie die Berechtigungen, die das Werkzeug braucht: `read` zum Lesen, `condition` zum Melden von Zustandsdaten und Lebenszyklusereignissen, `import` zum Zuordnen, Prüfen und Lesen von Tabellenimporten. Die Seite zeigt auch die folgenden Konfigurationen mit der Adresse Ihres Servers. 2. **Schlüssel als Umgebungsvariable bereitstellen** Der Schlüssel wird nur einmal angezeigt: Bewahren Sie ihn in Ihrem Passwortmanager auf. Die Konfigurationen unten lesen ihn beim Start des Werkzeugs aus der Umgebungsvariable `BATTERYPASS_API_KEY`. Setzen Sie die Variable in der Umgebung, aus der Ihr Werkzeug startet, zum Beispiel in der aktuellen Shell: ```bash title="macOS und Linux" export BATTERYPASS_API_KEY="bp_live_…" ``` ```powershell title="Windows (PowerShell)" $env:BATTERYPASS_API_KEY = "bp_live_…" ``` 3. **Server im Werkzeug eintragen** Folgen Sie unten dem Reiter Ihres Werkzeugs und lassen Sie sich danach die BatteryPass-Werkzeuge auflisten. ## Werkzeug einrichten **Claude Code** Tragen Sie den Server in die Projektdatei `.mcp.json` ein. Claude Code ersetzt `${BATTERYPASS_API_KEY}` bei jedem Start aus der Umgebung; so steht der Schlüssel weder in dieser Datei noch in der Konfiguration von Claude Code, und Sie können die Datei mit Ihrem Team teilen: ```json title=".mcp.json" { "mcpServers": { "batterypass": { "type": "http", "url": "https://passport.example.com/mcp", "headers": { "Authorization": "Bearer ${BATTERYPASS_API_KEY}" } } } } ``` Um den Server stattdessen für Ihren Benutzer in allen Projekten einzutragen, nutzen Sie die Kommandozeile mit `--scope user` (ohne diese Angabe gilt der Server nur für das aktuelle Projekt auf Ihrem Rechner): ```bash title="Terminal" claude mcp add --transport http --scope user batterypass https://passport.example.com/mcp \ --header "Authorization: Bearer bp_live_…" ``` > [!WARNING] > Die Kommandozeile speichert den Header samt Schlüssel im Klartext in der Konfiguration von Claude Code > (`~/.claude.json`), und Ihre Shell behält den Befehl womöglich im Verlauf. `$BATTERYPASS_API_KEY` im Befehl > ändert daran nichts: Die Shell ersetzt die Variable, bevor Claude Code sie sieht (und PowerShell braucht > `$env:BATTERYPASS_API_KEY`). Nutzen Sie `.mcp.json`, damit der Schlüssel in keiner Datei steht. Prüfen Sie die Verbindung mit `claude mcp list` oder mit `/mcp` in Claude Code. **Cursor** ```json title=".cursor/mcp.json" { "mcpServers": { "batterypass": { "url": "https://passport.example.com/mcp", "headers": { "Authorization": "Bearer ${env:BATTERYPASS_API_KEY}" } } } } ``` Starten Sie Cursor neu, nachdem Sie die Umgebungsvariable gesetzt haben; der Server erscheint dann unter **Settings → MCP**. **VS Code** VS Code fragt beim ersten Start des Servers nach dem Schlüssel und legt ihn in seinem Geheimnisspeicher ab: ```json title=".vscode/mcp.json" { "inputs": [ { "type": "promptString", "id": "batterypass-api-key", "description": "BatteryPass API key", "password": true } ], "servers": { "batterypass": { "type": "http", "url": "https://passport.example.com/mcp", "headers": { "Authorization": "Bearer ${input:batterypass-api-key}" } } } } ``` **Andere Clients** Ein Client, der nur lokale Server (stdio) startet, erreicht BatteryPass über die Brücke `mcp-remote`. Legen Sie den ganzen Header in eine Umgebungsvariable, weil manche Clients Argumente an Leerzeichen trennen: ```json title="Client-Konfiguration" { "mcpServers": { "batterypass": { "command": "npx", "args": ["-y", "mcp-remote@0.15.2", "https://passport.example.com/mcp", "--header", "Authorization:${AUTH_HEADER}"], "env": { "AUTH_HEADER": "Bearer bp_live_…" } } } } ``` > [!NOTE] > Connectoren in claude.ai, Claude Desktop und ChatGPT, die sich nur per OAuth anmelden können, lassen sich noch nicht > verbinden: Der MCP-Server akzeptiert ausschließlich API-Schlüssel. Nutzen Sie stattdessen Claude Code, Cursor, > VS Code oder `mcp-remote`. ## Die Werkzeuge Jede Operation der veröffentlichten Integrations-API ist ein Werkzeug, außer dem Datei-Upload `createImport`. Sein Name ist die `operationId` der Operation in snake_case: Aus `listBatteryModels` in der API-Referenz wird das Werkzeug `list_battery_models`. Die Argumente eines Werkzeugs sind die Pfad- und Query-Parameter der Operation unter ihren Namen und der JSON-Body unter `body`; die Beschreibungen stammen aus der API-Referenz und nennen die nötige Berechtigung. | Berechtigung | Werkzeuge | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `read` | Katalog: `list_battery_models`, `get_battery_model`, `list_model_versions`, `get_model_version`, `list_batteries`, `get_battery`, `export_units`, `list_facilities` | | `read` | Werte und Vollständigkeit: `list_model_version_values`, `list_model_version_value_history`, `get_model_version_completeness`, `list_battery_values`, `list_battery_value_history`, `get_battery_completeness` | | `read` | Pässe: `get_passport`, `list_passport_versions`, `get_passport_version`, `get_passport_version_diff`, `export_passport_json`, `export_passport_pdf`, `get_passport_qr`, `get_registry_submission_status` | | `read` | Lebenszyklus, Dokumente und Register: `list_lifecycle_events`, `get_condition`, `list_evidence`, `get_evidence`, `download_evidence`, `get_registry_info`, `get_registry_schema`, `get_registry_status` | | `read` | Änderungsfeed: `list_changes` | | `condition` | `update_condition` (gemessene Zustandsdaten melden), `create_lifecycle_event` | | `import` | `list_imports`, `get_import`, `update_import_mapping`, `validate_import` | | keine (öffentlich) | `get_public_passport`, `get_public_passport_version`, `get_public_passport_by_product_id`, `verify_passport`, `download_public_passport_document` | Ein Werkzeug sieht nur die Daten der Organisation, der der Schlüssel gehört, genau wie eine REST-Anfrage mit diesem Schlüssel. Ihr Werkzeug listet nur die Werkzeuge der Berechtigungen des Schlüssels auf; öffentliche Passabfragen stehen jedem Schlüssel zur Verfügung. Ein Werkzeug kann keine Datei übertragen. Eine Tabelle laden Sie daher mit demselben Schlüssel über REST mit [`createImport`](https://passport.kabin.sh/docs/de/api-reference/imports/create-import) hoch; danach ordnet der Assistent den Import mit den Werkzeugen zu und prüft ihn ([Einheiten aus der Fertigung](https://passport.kabin.sh/docs/de/integrations/workflows/units-from-production)). Das Übernehmen des Imports und das Freigeben seiner Werte bleiben bei Mitgliedern im Portal. So kommen Ergebnisse zurück: - JSON-Antworten kommen als Text und als strukturierter Inhalt. - Listen liefern eine Seite. Die Beschreibungen bitten den Assistenten, ein kleines `limit` zu übergeben und mit `cursor` gleich `next_cursor` erneut abzufragen, bis es `null` ist. - Dateien (PDF, QR-Codes als PNG oder SVG, Tabellen, Dokumente) kommen bis 1 MiB als eingebettete Ressource. Größere Dateien scheitern mit `result_too_large`; laden Sie sie dann mit dem Schlüssel über REST herunter. - Ein Fehler der API ist ein Werkzeugfehler mit `code`, `title`, `detail`, den Feldfehlern `errors` und der `request_id` des Problems, zum Beispiel `not_found` oder `validation_error`. Argumente, die nicht zum Schema des Werkzeugs passen, scheitern mit `invalid_arguments`, bevor etwas gesendet wird. > [!TIP] > Schreibend sind nur die beiden `condition`-Werkzeuge sowie `update_import_mapping` und `validate_import`. Sie stehen > in Ihrem Audit-Log mit dem Schlüssel als Akteur und dem Vermerk `channel: mcp`. Nach einer Zustandsmeldung kann ein > veröffentlichter Pass je nach Einstellung Ihrer Organisation sofort neu veröffentlicht werden. Lassen Sie Ihr > Werkzeug vor dem Aufruf nachfragen. ## Sicherheit - **Ein Schlüssel je Werkzeug und Person.** So sehen Sie im Audit-Log, wer gehandelt hat, und widerrufen ein Werkzeug, ohne die anderen zu berühren. - **So wenig Berechtigungen wie möglich.** Geben Sie `condition` nur Werkzeugen, die Messwerte melden müssen, und `import` nur Werkzeugen, die Importe vorbereiten; ein `read`-Schlüssel kann nichts ändern. - **Widerrufen** Sie einen Schlüssel auf der Seite API-Schlüssel, sobald ein Werkzeug oder Laptop nicht mehr genutzt wird. Der Widerruf wirkt sofort. - **Ergebnisse sind Daten, keine Anweisungen.** Werte, Notizen und Dokumente in BatteryPass stammen von Ihrem Team, Ihren Lieferanten und Servicepartnern. Der Server weist den Assistenten an, sie als Daten zu behandeln; prüfen Sie trotzdem, was ein Assistent schreiben will. - Legen Sie einen Schlüssel nie in ein Repository, eine URL oder eine Chatnachricht. Die Konfigurationsdateien oben lesen ihn aus der Umgebung; nur der Befehl `claude mcp add` und die Konfiguration von `mcp-remote` enthalten ihn im Klartext. ## Fehlerbehebung | Antwort | Ursache und Abhilfe | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401 unauthenticated` | Kein Schlüssel, ein vertippter oder ein widerrufener Schlüssel: Die Antwort ist in allen drei Fällen gleich. Prüfen Sie, ob die Umgebungsvariable in der Umgebung gesetzt ist, aus der das Werkzeug startet, und ob der Header `Authorization: Bearer bp_live_…` lautet. | | `403 forbidden` beim Verbinden | Ein Client im Browser auf einem anderen Web-Origin hat einen `Origin`-Header gesendet. Browser-Clients auf anderen Origins werden nicht unterstützt; nutzen Sie einen Desktop-Client oder die Brücke `mcp-remote`. | | `400` mit dem JSON-RPC-Fehler `-32600` | Der Client hat einen Batch gesendet (mehrere Nachrichten in einer Anfrage). Senden Sie eine Nachricht je Anfrage; aktuelle Clients tun das. | | Werkzeugfehler `403 forbidden` | Das Werkzeug braucht eine Berechtigung, die Ihr Schlüssel nicht hat, zum Beispiel `condition`. Erstellen Sie einen Schlüssel mit dieser Berechtigung. | | `405 method not allowed` | Etwas hat ein `GET` (oder `DELETE`) an `/mcp` gesendet. Der Server beantwortet nur `POST`; aktualisieren Sie den Client oder wählen Sie den Transport Streamable HTTP (`--transport http`). | | `404 not found` | Die Adresse ist falsch, oder der Administrator hat MCP abgeschaltet (`MCP_ENABLED=false`). | | `429 rate_limited` oder Werkzeugfehler `rate_limited` | Alle Schlüssel Ihrer Organisation zusammen dürfen 600 Anfragen pro Minute stellen, und jeder Werkzeugaufruf zählt doppelt (die MCP-Anfrage und die API-Anfrage, die er auslöst). Warten Sie die Sekunden aus `Retry-After` ab (`retry_after_seconds` in Werkzeugfehlern). Wiederholt falsche Schlüssel von einer Adresse sind auf 30 Versuche in 15 Minuten begrenzt. | [**API-Referenz**](https://passport.kabin.sh/docs/de/api-reference): Jede Operation hinter den Werkzeugen, mit Parametern, Antworten und Fehlercodes. [**API-Schlüssel**](https://passport.kabin.sh/settings/api-keys): Schlüssel im BatteryPass-Portal erstellen und widerrufen (nur Eigentümer).