Demo ausprobieren Demo

Entwicklerportal

Jede ConvoyPlan-Installation stellt eine REST-API und einen MCP-Server bereit. Damit lassen sich Marschverbände, Fahrzeuge, Wegpunkte, Routen und Live-Positionen aus anderen Systemen und von KI-Agenten lesen und planen.

Kein öffentlicher Endpunkt auf dieser Domain. ConvoyPlan verarbeitet Einsatzdaten von BOS-Organisationen. Die API läuft deshalb ausschließlich in der Installation der jeweiligen Organisation, und Zugangsdaten stellt deren Administration aus — nicht wir. Einen Self-Service für API-Keys gibt es bewusst nicht.

Einstiegspunkte

SchnittstelleAdresseAuthentifizierung
REST-API https://{instanz}/api Authorization: Bearer <JWT> oder X-API-Key
MCP-Server https://{instanz}/mcp OAuth 2.0 mit PKCE (S256)
WebSocket (Live-Tracking) https://{instanz}/api wie REST

Die öffentlich erreichbare Instanz läuft unter https://web.convoyplan.de/api; ihre Daten gehören dem Betreiber, ein Zugang wird nicht frei vergeben.

Authentifizierung

Drei Verfahren, je nachdem, in wessen Namen gearbeitet wird:

Ein Aufruf ohne gültiges Token antwortet mit 401 und WWW-Authenticate: Bearer. Der vollständige Ablauf — von der Beschaffung bis zum Widerruf — steht als Markdown unter auth.md.

Berechtigungen

Jeder Zugriff ist auf eine Organisation und eine Rolle begrenzt: Admin, Planer, Fahrer oder Beobachter. Ein Beobachter-Token kann nicht schreiben, ein Organisations-Key sieht keine fremden Mandanten. Einzelheiten stehen im Wiki.

Testumgebung: Demo-Modus

Eine Installation ohne Lizenzschlüssel startet im Demo-Modus. Lesende Zugriffe sind frei, schreibende antworten mit HTTP 402 Payment Required. Der Demo-Modus ist dauerhaft kostenlos und genau dafür gedacht, eine Integration gegen echte Endpunkte zu entwickeln, ohne Einsatzdaten zu verändern. Eine eigene Instanz steht mit einem Befehl: 

curl -fsSL https://convoyplan.de/install.sh | bash

Unter Windows: irm https://convoyplan.de/install.ps1 | iex in einer PowerShell mit Administratorrechten.

OpenAPI-Spezifikation

Das Backend erzeugt eine OpenAPI-Spezifikation, liefert sie im Produktivbetrieb aber nicht offen aus: /docs, /redoc und /openapi.json antworten standardmäßig mit 404. Der Betreiber schaltet sie frei — entweder geschützt über DOCS_API_KEY (Abruf dann mit X-API-Key) oder offen über ENABLE_DOCS=true. Eine öffentlich gehostete Spezifikation auf dieser Domain gibt es nicht, weil sie nicht zu einer bestimmten Instanz gehören würde.

MCP-Server

Der MCP-Server bringt lesende Tools für Marschverbände, Unterverbände, Fahrzeuge, Wegpunkte, gespeicherte Routen, letzte Positionen und Marschstatus mit sowie schreibende Tools für Planung, Fahrzeugzuordnung, Wegpunkte, Routenberechnung und Statusmeldungen. Dazu kommen Ressourcen für Dokumente und Live-Abonnements. Die Adresse steht im Admin-Portal der Instanz; ein Client registriert sie als Remote-MCP-Server und meldet sich per OAuth an. Der maschinenlesbare Steckbrief liegt unter /.well-known/mcp/server-card.json.

Ein 404 auf /mcp ist eine Antwort, kein Fehler. Die Schnittstelle ist standardmäßig abgeschaltet und dann nicht montiert — es gibt keinen Endpunkt und keine Discovery-Dokumente. Eingeschaltet wird sie vom Betreiber der Instanz; zusätzlich gibt der Admin jeder Organisation ihre Teilnahme einzeln frei, je Bereich (Konvois, Fahrzeuge, Wegpunkte, Routen, Positionen, Status). Was danach durchgeht, entscheidet die Zustimmung eines angemeldeten Benutzers auf /oauth/consent — für genau eine Organisation und gedeckelt durch dessen Rolle. Die Werkzeugliste aus tools/list ist deshalb instanz- und verbindungsabhängig; sie zu cachen und wiederzuverwenden geht schief.

Jedes Werkzeug trägt Verhaltenszusagen (readOnlyHint, destructiveHint, openWorldHint); als zerstörend ist keines markiert, weil keines löscht. Alle Werkzeuge antworten zusätzlich strukturiert (structuredContent) statt nur als Text — die Felder sind benannt und müssen nicht aus einem Textblock gefischt werden. Für Clients mit Oberfläche liegen drei Ansichten bei (Konvoi-Liste, Konvoi-Übersicht, Marschstatus); sie laden nichts von außen nach und sind Zugabe: ein Programm ohne Oberflächen bekommt dieselbe Antwort wie bisher.

Der Weg für ChatGPT läuft über den Developer Mode, nicht über das App-Verzeichnis — ein Verzeichniseintrag könnte immer nur auf eine Adresse zeigen und wäre für jede andere Instanz wertlos. Die Anleitung im Wiki nennt die drei Stolpersteine: das fehlende /mcp am Ende der Adresse, die Verbindung, die je Unterhaltung eingeschaltet werden muss, und den Haken bei den Schreibrechten beim Zustimmen — den ChatGPT später nicht nachfordern kann.

Was eine Instanz über sich selbst ausliefert

Für den ersten Aufruf gegen eine unbekannte Installation: GET /api/status/capabilities sagt ohne Anmeldung, ob der MCP-Server montiert ist, ob ein Demo-Zugang besteht und wo die maschinenlesbaren Beschreibungen liegen. Daneben liefert jede Instanz unter ihrer eigenen Domain /llms.txt, /agents.md, /auth.md, /api.md, eine kuratierte /openapi.json der anmeldefreien Endpunkte, die Well-Known-Dokumente (Agent Card, Agent Skills, ARD, MCP Server Card, API-Katalog, Resource-Metadaten nach RFC 9728) und /ask für Fragen über die Software. Markdown gibt es über Accept: text/markdown, über .md und über ?mode=agent — nicht danach, ob sich ein Abrufer als Bot zu erkennen gibt.

Alles davon gehört zur Instanz und lässt sich mit AGENT_DISCOVERY=false abschalten; dann existieren diese Pfade nicht. Auf dieser Domain gibt es die Gegenstücke unter /llms.txt und /llms.md.

Für Agenten

Dokumentation

Fragen zu einer Integration, die hier nicht beantwortet sind: anfrage@convoyplan.de.