KI-Werkzeuge über MCP anbinden

BatteryPass betreibt einen Model-Context-Protocol-Server (MCP) unter https://<Ihr BatteryPass-Host>/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.

Bevor Sie beginnenLink zum Abschnitt kopieren

export BATTERYPASS_API_KEY="bp_live_…"

Werkzeug einrichtenLink zum Abschnitt kopieren

{
  "mcpServers": {
    "batterypass": {
      "type": "http",
      "url": "https://passport.example.com/mcp",
      "headers": { "Authorization": "Bearer ${BATTERYPASS_API_KEY}" }
    }
  }
}

claude mcp add --transport http --scope user batterypass https://passport.example.com/mcp \
  --header "Authorization: Bearer bp_live_…"

Die WerkzeugeLink zum Abschnitt kopieren

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.

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 hoch; danach ordnet der Assistent den Import mit den Werkzeugen zu und prüft ihn (Einheiten aus der Fertigung). 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.

SicherheitLink zum Abschnitt kopieren

• 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.

FehlerbehebungLink zum Abschnitt kopieren