---
title: "ConvoyPlan für Entwickler"
description: "REST-API und MCP-Server jeder ConvoyPlan-Installation: Authentifizierung, API-Keys, Testumgebung im Demo-Modus, OpenAPI-Spezifikation und Dokumentation."
canonical: "https://convoyplan.de/developers/"
last-updated: 2026-11-13
---

# ConvoyPlan für Entwickler

> REST-API und MCP-Server jeder ConvoyPlan-Installation: Authentifizierung, API-Keys, Testumgebung im Demo-Modus, OpenAPI-Spezifikation und Dokumentation.

Quelle: <https://convoyplan.de/developers/> · Site-Index: <https://convoyplan.de/llms.txt>

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

## Einstiegspunkte

| Schnittstelle | Adresse | Authentifizierung |
|---|---|---|
| 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

1. **OAuth 2.0 mit PKCE über MCP** — der vorgesehene Weg für KI-Agenten. Ein Mensch
   meldet sich im Browser an, wählt die Organisation und erteilt die Freigabe.
   Berechtigungen werden bei jedem Aufruf frisch gegen die Datenbank geprüft.
2. **JWT** — `POST /api/auth/login` liefert ein Token für einen Benutzeraccount,
   optional mit TOTP als zweitem Faktor.
3. **API-Key** — `X-API-Key: cvp_<prefix>_<secret>` für Dienst-zu-Dienst-Integrationen
   ohne Benutzerkontext. Ausgestellt im Superadmin-Portal unter Admin → API-Keys,
   wahlweise für eine Organisation oder systemweit, mit fester Rolle.

Ein Aufruf ohne gültiges Token antwortet mit `401` und `WWW-Authenticate: Bearer`.
Der vollständige Ablauf bis zum Widerruf steht in <https://convoyplan.de/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 im Wiki: <https://github.com/RettTechSolutions/ConvoyPlan/wiki>

## Testumgebung: Demo-Modus (sandbox / test environment)

Eine Installation ohne Lizenzschlüssel startet im Demo-Modus. Lesende Zugriffe sind frei, schreibende Zugriffe antworten mit `HTTP 402 Payment Required`. Der Demo-Modus ist dauerhaft kostenlos und dafür gedacht, Integrationen gegen echte Endpunkte zu entwickeln, ohne Einsatzdaten zu verändern.

Eigene Instanz in einem Befehl:

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

Unter Windows in einer PowerShell mit Administratorrechten:

```powershell
irm https://convoyplan.de/install.ps1 | iex
```

Dokumentation: <https://github.com/RettTechSolutions/ConvoyPlan/wiki/Lizenz-und-Demo-Modus>

## 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 — 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 zu keiner bestimmten Instanz
gehören würde.

## MCP-Server

Lesende Tools für Marschverbände, Unterverbände, Fahrzeuge, Wegpunkte, gespeicherte
Routen, letzte Positionen und Marschstatus; schreibende Tools für Planung,
Fahrzeugzuordnung, Wegpunkte, Routenberechnung und Statusmeldungen. Dazu 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.

**Ein `404` auf `/mcp` ist eine Antwort, kein Fehler.** Die Schnittstelle ist
standardmäßig abgeschaltet und dann nicht montiert — kein Endpunkt, keine
Discovery-Dokumente. Die Werkzeugliste aus `tools/list` ist instanz- und
verbindungsabhängig; sie zu cachen und wiederzuverwenden geht schief.

- **Standardmäßig aus**: Abgeschaltet montiert die Instanz keinen einzigen Endpunkt — es gibt nichts, was ein 404 nur zudeckt. Einschalten heißt, Einsatzdaten für einen externen Modellanbieter zu öffnen; diese Entscheidung gehört dem Betreiber und nicht dem Auslieferungszustand.
- **Zwei Schalter, beide nötig**: Der Betreiber schaltet die Schnittstelle auf der Instanz frei, der Admin jeder Organisation ihre Teilnahme — einzeln je Bereich: Konvois, Fahrzeuge, Wegpunkte, Routen, Positionen und Status. Wer eine Instanz für mehrere Organisationen betreibt, entscheidet damit nicht über deren Einsatzdaten.
- **Ein Mensch stimmt zu**: Zugriff entsteht erst durch die Zustimmung eines angemeldeten Benutzers im Browser: für genau eine Organisation, gedeckelt durch seine Rolle. Auf dem Zustimmungsbildschirm sind die Rechte einzeln ankreuzbar — ein Beobachter bekommt Schreibrechte auch durch Ankreuzen nicht.
- **Kein Werkzeug löscht**: Es gibt kein Werkzeug, das einen Konvoi, ein Fahrzeug, einen Wegpunkt, eine Route oder einen Benutzer löscht — und keines für Benutzerverwaltung, Lizenz oder Systemeinstellungen. Jeder schreibende Aufruf steht im Audit-Log mit Quelle „mcp"; einzelne Verbindungen lassen sich jederzeit trennen.

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.
Für Clients mit Oberfläche liegen drei Ansichten bei, die nichts von außen nachladen.

Der Weg für ChatGPT läuft über den Developer Mode, nicht über das App-Verzeichnis:
<https://github.com/RettTechSolutions/ConvoyPlan/wiki/ChatGPT-verbinden>

Steckbrief: <https://convoyplan.de/.well-known/mcp/server-card.json> · Dokumentation: <https://github.com/RettTechSolutions/ConvoyPlan/wiki/MCP-Server>

## Was eine Instanz über sich selbst ausliefert

`GET /api/status/capabilities` sagt ohne Anmeldung, ob der MCP-Server montiert ist, ob
ein Demo-Zugang besteht und wo die maschinenlesbaren Beschreibungen liegen — der
richtige erste Aufruf gegen eine unbekannte Installation. 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`. Markdown gibt es über `Accept: text/markdown`, über `.md` und
über `?mode=agent` — nicht nach User-Agent. Abschaltbar mit `AGENT_DISCOVERY=false`;
dann existieren diese Pfade nicht.

Beschreibung: <https://github.com/RettTechSolutions/ConvoyPlan/wiki/Agenten-Auskunft>

## Maschinenlesbare Dokumente

- <https://convoyplan.de/developers/llms.txt> — Kontext nur zu diesem Bereich
- <https://convoyplan.de/auth.md> — Zugangsdaten beschaffen und widerrufen
- <https://convoyplan.de/.well-known/agent-skills/index.json> — Agent Skills
- <https://convoyplan.de/.well-known/api-catalog> — API-Katalog nach RFC 9727
- <https://convoyplan.de/.well-known/ard.json> — Agentic Resource Discovery

## Dokumentation

- [API-Dokumentation — alle REST- und WebSocket-Endpunkte](https://github.com/RettTechSolutions/ConvoyPlan/wiki/API-Dokumentation)
- [MCP-Server](https://github.com/RettTechSolutions/ConvoyPlan/wiki/MCP-Server)
- [ChatGPT verbinden](https://github.com/RettTechSolutions/ConvoyPlan/wiki/ChatGPT-verbinden)
- [Agenten-Auskunft der Instanz](https://github.com/RettTechSolutions/ConvoyPlan/wiki/Agenten-Auskunft)
- [Installation und Setup](https://github.com/RettTechSolutions/ConvoyPlan/wiki/Installation-und-Setup)
- [Entwicklung](https://github.com/RettTechSolutions/ConvoyPlan/wiki/Entwicklung)
- [Changelog](https://github.com/RettTechSolutions/ConvoyPlan/blob/main/CHANGELOG.md)

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