Planfix MCP

MCP (Model Context Protocol) ermöglicht KI-Assistenten und anderen kompatiblen Anwendungen, über ein Standardprotokoll mit Planfix-Daten zu arbeiten.

Nach dem Herstellen einer Verbindung erhält der Client nur die ausdrücklich erlaubten Funktionen und handelt im Namen des angemeldeten Mitarbeiters. Die standardmäßigen Planfix-Zugriffsberechtigungen gelten weiterhin: Ein KI-Assistent kann nichts anzeigen oder ändern, worauf dieser Benutzer keinen Zugriff hat.

Die verfügbaren Aktionen hängen vom MCP-Client, den gewährten Berechtigungen und der aktuellen Serverversion ab. Ein Client kann beispielsweise Aufgaben und Kontakte finden, deren Details lesen und Kommentare hinzufügen, sofern die entsprechenden Berechtigungen erteilt wurden.

Voraussetzungen

ein Planfix-Mitarbeiterkonto;
ein MCP-Client, der Streamable HTTP und OAuth unterstützt.

MCP-Serveradresse

Verwenden Sie diese MCP-Server-URL:

https://mcp.planfix.com/mcp

Die URL ist für alle Planfix-Konten identisch. Fügen Sie keinen Kontonamen hinzu und senden Sie keinen separaten Konto-Header. Das Konto wird während der OAuth-Autorisierung ausgewählt.

Verbindung mit einem beliebigen MCP-Client herstellen

Öffnen Sie die MCP-Servereinstellungen im Client.
Fügen Sie einen neuen Server mit dem Transport Streamable HTTP hinzu.
Geben Sie einen Namen wie Planfix und die MCP-URL ein.
Speichern Sie die Einstellungen und starten Sie die OAuth-Authentifizierung.
Wählen Sie im daraufhin geöffneten Browserfenster Ihr Planfix-Konto aus. Sie können es anhand des Namens, der URL oder der E-Mail-Adresse finden.
Prüfen Sie den Namen der Anwendung und die angeforderten Berechtigungen und bestätigen Sie anschließend die Verbindung.

Wenn die Anwendung im Konto noch nicht zugelassen wurde, weist Planfix darauf hin, dass eine Genehmigung durch einen Administrator erforderlich ist. Ein Kontoadministrator oder technischer Administrator kann die Anwendung genehmigen. Wenn der Administrator die Verbindung selbst herstellt, kann er sie in einem Schritt genehmigen und verbinden.

Bei einer DCR-Verbindung mit Codex kann die Anfrage nach Beginn der Anmeldung nicht an einen Administrator weitergeleitet werden. Wählen Sie daher vorab das passende Szenario im nächsten Abschnitt aus.

Codex verbinden

Wählen Sie die passende Option aus, je nachdem, ob Sie Administrator des Kontos sind, mit dem die Verbindung hergestellt werden soll.

Wenn Sie Administrator sind: Verbindung über DCR herstellen

Diese Option ist für den Kontoadministrator oder den technischen Administrator verfügbar. Während der Anmeldung können sie sowohl die automatisch registrierte Anwendung genehmigen als auch die Verbindung herstellen.

Fügen Sie den MCP-Server hinzu:

codex mcp add planfix --url https://mcp.planfix.com/mcp

Starten Sie die OAuth-Anmeldung und wählen Sie ausdrücklich DCR als Methode zur Clientregistrierung aus:

codex mcp login planfix --oauth-client-registration dcr

Codex öffnet den Browser. Wählen Sie das Planfix-Konto aus, in dem Sie Administrator sind, prüfen Sie die angeforderten Berechtigungen und klicken Sie auf Genehmigen und verbinden.

Eine über DCR registrierte Anwendung muss immer ausdrücklich vom Konto genehmigt werden. Ein regulärer Mitarbeiter sollte dieses Szenario nicht starten: Derzeit kann eine DCR-Verbindungsanfrage nicht zurückgestellt und zur separaten Genehmigung an einen Administrator weitergeleitet werden.

Der Parameter --oauth-client-registration dcr gilt nur für diese Anmeldung und wird nicht in config.toml gespeichert. Codex speichert die erhaltenen OAuth-Verbindungsdaten selbst.

Wenn Sie kein Administrator sind: Verbindung mit client_id herstellen

Bitten Sie zunächst den Kontoadministrator oder den technischen Administrator, eine Anwendung zu erstellen:

Öffnen Sie Kontoverwaltung → API → OAuth- und MCP-Anwendungen.
Klicken Sie im Abschnitt Anwendungen dieses Kontos auf Anwendung erstellen.
Geben Sie einen Namen ein, zum Beispiel Codex.
Wählen Sie den Typ Öffentlicher Client. Für Codex ist kein Client-Secret erforderlich.
Fügen Sie die Redirect-URI http://127.0.0.1/callback hinzu.
Wählen Sie die mindestens erforderlichen Berechtigungen aus und speichern Sie die Anwendung.
Teilen Sie dem Benutzer die erhaltene client_id mit.

Planfix veröffentlicht den Issuer und unterstützt die Bindung der Autorisierungsantwort an diesen. Daher verwendet ein neuer, vorregistrierter Codex-Client den stabilen Callback http://127.0.0.1/callback. Während der Anmeldung fügt Codex einen temporären Loopback-Port hinzu. Planfix akzeptiert einen solchen Port, sofern Host und Pfad unverändert bleiben.

Der Benutzer fügt den Server hinzu und ersetzt dabei die angegebene Kennung:

codex mcp add planfix --url https://mcp.planfix.com/mcp --oauth-client-id CLIENT_ID

Codex zeigt die vollständige Callback-URL an. In der Standardkonfiguration sieht sie so aus:

OAuth callback URL: http://127.0.0.1/callback

Wird aufgrund benutzerdefinierter Codex-Einstellungen eine andere Adresse angezeigt, bitten Sie den Administrator, diese Redirect-URI zur Anwendung hinzuzufügen.

Führen Sie anschließend folgenden Befehl aus:

codex mcp login planfix

Durch die Angabe von --oauth-client-id verwendet Codex den vorregistrierten Client und startet weder CIMD noch DCR. Die Einstellungen werden ungefähr so gespeichert:

[mcp_servers.planfix]
url = "https://mcp.planfix.com/mcp"

[mcp_servers.planfix.oauth]
client_id = "CLIENT_ID"
callback_url = "http://127.0.0.1/callback"

Codex-App und IDE-Erweiterung

Die Codex-App, die Codex-CLI und die IDE-Erweiterung verwenden auf demselben Computer eine gemeinsame MCP-Konfiguration. Starten Sie nach der ersten Verbindung über die CLI die App oder die Erweiterung neu. Der Server wird unter Einstellungen → MCP-Server angezeigt. Wenn daneben Authentifizieren angezeigt wird, klicken Sie auf diese Schaltfläche und schließen Sie die Anmeldung ab.

Mit dem Befehl /mcp im Eingabefeld von Codex können Sie die aktiven MCP-Server überprüfen.

Die Liste und den Status der Verbindungen können Sie mit folgendem Befehl anzeigen:

codex mcp list

Die aktuellen UI-Elemente, Befehle und Regeln zur Auswahl des Callbacks werden in der offiziellen OpenAI-MCP-Dokumentation beschrieben.

Wenn ein anderer MCP-Client keine automatische Registrierung durchführen kann

Ein moderner MCP-Client kann sich automatisch über CIMD oder DCR registrieren. Eine solche Registrierung gewährt für sich genommen keinen Zugriff auf das Konto: Die Kontorichtlinien und die Genehmigung durch einen Administrator gelten weiterhin.

Wenn der Client eine vordefinierte client_id benötigt, bitten Sie den Administrator, eine öffentliche Anwendung für das Konto zu erstellen:

Öffnen Sie Kontoverwaltung → API → OAuth- und MCP-Anwendungen.
Erstellen Sie im Abschnitt Anwendungen dieses Kontos eine Anwendung.
Wählen Sie den Typ Öffentlicher Client.
Fügen Sie die vom MCP-Client angezeigte Redirect-URI hinzu.
Wählen Sie die mindestens erforderlichen Berechtigungen aus.
Teilen Sie dem Benutzer die erhaltene client_id mit oder fügen Sie sie zu den Clienteinstellungen hinzu.

Eine solche Anwendung kann nur eine Verbindung mit dem Konto herstellen, in dem sie erstellt wurde. Weitere Informationen finden Sie im Artikel OAuth- und MCP-Anwendungen in einem Konto.

Mehrere Konten

Jede Verbindung ist einem Konto und einem Benutzer zugeordnet.

Für eine DCR-Verbindung fügen Sie unter einem anderen Namen einen weiteren MCP-Server hinzu. Wählen Sie während der Anmeldung ein anderes Konto aus, in dem Sie Administratorrechte haben.
Eine kontoeigene Anwendung und ihre client_id funktionieren nur in dem Konto, in dem sie erstellt wurden. Für ein anderes Konto muss dessen Administrator eine separate öffentliche Anwendung erstellen. Fügen Sie sie unter einem anderen Namen und mit der neuen client_id zu Codex hinzu.

Ändern Sie die MCP-URL nicht und fügen Sie den Kontonamen nicht zu Anfragen hinzu. Der Server ermittelt das Konto anhand des ausgestellten OAuth-Tokens.

MCP-Verbindung trennen

So widerrufen Sie Ihre Verbindung:

Öffnen Sie Ihre Benutzerkarte in Planfix.
Gehen Sie zu Sitzungsverwaltung.
Suchen Sie die mit MCP gekennzeichnete Anwendung und löschen Sie die Sitzung.
Entfernen oder deaktivieren Sie den Server im MCP-Client, wenn Sie ihn nicht mehr benötigen.

Durch das Löschen der Sitzung werden die zugehörigen OAuth-Tokens widerrufen. Für eine erneute Verbindung sind eine neue Anmeldung und Zustimmung erforderlich.

Ein Administrator kann eine Anwendung für das gesamte Konto unter Kontoverwaltung → API → OAuth- und MCP-Anwendungen widerrufen.

Sicherheit

Verbinden Sie nur Anwendungen, denen Sie vertrauen.
Prüfen Sie vor der Genehmigung den Anwendungsnamen, den Inhaber, die Redirect-URI und die angeforderten Berechtigungen.
Gewähren Sie nur die minimal erforderlichen Berechtigungen. Erteilen Sie bei einer schreibgeschützten Nutzung keine Berechtigungen zum Ändern oder Löschen.
Fügen Sie niemals ein Zugriffstoken oder Refresh-Token in einen Chat, in Anfrageeinstellungen oder in Protokolle ein.
Beachten Sie, dass Inhalte von Aufgaben, Kontakten und Kommentaren gemäß den Datenverarbeitungsbedingungen des jeweiligen Dienstes an einen externen KI-Dienst gesendet werden können.
Entfernen Sie eine Verbindung aus der Sitzungsverwaltung, wenn sie nicht mehr verwendet wird oder Ihnen unbekannt ist.

Fehlerbehebung

Wenn bei der DCR-Anmeldung eine Genehmigung durch einen Administrator erforderlich ist, melden Sie sich als Kontoadministrator oder technischer Administrator an und klicken Sie auf Genehmigen und verbinden. Ein regulärer Mitarbeiter kann eine gestartete DCR-Anfrage nicht zur separaten Genehmigung weiterleiten.

Meldung oder Symptom	Vorgehensweise
Die Anwendung wird durch die Kontorichtlinie blockiert	Ein Administrator muss die betreffende Anwendung genehmigen oder die Richtlinie für Drittanbieteranwendungen ändern.
Der Client fordert nach der Anmeldung erneut eine Autorisierung an	Entfernen Sie die Verbindung aus dem Client und richten Sie sie erneut ein. Vergewissern Sie sich, dass die exakte MCP-URL verwendet wird.
Es wurde das falsche Konto ausgewählt	Widerrufen Sie die Verbindung und melden Sie sich erneut an. Wählen Sie dabei das richtige Konto aus. Ein Token kann nicht einem anderen Konto zugeordnet werden.
Der Client fordert eine `client_id` an	Bitten Sie den Administrator, eine öffentliche Anwendung für das Konto zu erstellen, und fügen Sie den MCP-Server mit dem Parameter `--oauth-client-id` hinzu.
Ein Vorgang ist nicht verfügbar	Prüfen Sie die gewährten Scopes und die eigenen Zugriffsberechtigungen des Benutzers in Planfix.