Die meisten Fehler liegen am Key, an der Adresse oder an den Rechten des Actor-Users. Die Meldung sagt meist schon, was fehlt.
Verbindung und Key
| Antwort | Ursache | Lösung |
|---|---|---|
401 mit API-Key fehlt | Der Header X-API-KEY kommt nicht an. | Konfiguration prüfen, bei Umgebungsvariablen: ist sie gesetzt? |
401 mit Ungueltiger oder fehlender API-Key | Schlüssel falsch, gekürzt oder widerrufen, oder der Mandant ist nicht mehr aktiv. | Schlüssel neu eintragen oder einen neuen ausgeben lassen. |
401 mit API-Schlüssel abgelaufen | Das Ablaufdatum ist erreicht, oder nach einer Rotation ist die Übergangsfrist des alten Schlüssels vorbei. | Den neuen Schlüssel eintragen oder einen neuen ausgeben lassen. |
403 mit API-Key fehlt Scope: app-tools | Der Schlüssel ist für eine Spezialanbindung ausgestellt. | Einen App-Tools-Schlüssel verwenden. |
403 mit API-Key hat keinen Actor-User | Dem Schlüssel fehlt der technische Benutzer. | Schlüssel mit Actor-User ausgeben lassen. |
405 | Der Client ruft die Adresse per GET auf. | Im Client die Übertragung „Streamable HTTP“ bzw. http wählen. |
Werkzeuge
| Antwort | Ursache | Lösung |
|---|---|---|
Unbekanntes Tool | Name mit Punkt, Filter an der Adresse oder fehlende Rechte. | Namen aus der Tool-Liste des Clients nehmen, Filter und Rechte prüfen. |
Unbekanntes Tool … nur search_tools und call_tool | Die Adresse enthält modus=suche. | Werkzeuge über call_tool aufrufen oder modus=suche aus der Adresse nehmen. |
Ergebnis beginnt mit Fehler: | Eingabe, Rechte oder fachlicher Zustand passen nicht. | Die Meldung sagt, was fehlt. Der Assistent kann die Eingabe damit meist selbst korrigieren. |
Code-Mode
| Antwort | Ursache | Lösung |
|---|---|---|
403 mit Dieser API-Schlüssel ist im Code-Mode: Werkzeuge nur über Programme | Der Key steht im Code-Mode und ruft ein Werkzeug einzeln auf. | Programme über code_ausfuehren schicken oder einen klassischen Key verwenden. |
Code-Mode ist an diesem API-Schlüssel ausgeschaltet | Der Key ist klassisch (ab Werk) oder wurde während eines Laufs umgestellt. | Ein Plattform-Admin schaltet Code-Mode ein: Code-Mode einschalten und absichern. |
Die Code-Ausführung ist auf dieser Instanz nicht eingeschaltet | Auf dem Server deiner Instanz fehlt die Sandbox für Programme. | Bei deinem Ansprechpartner von United Synergy nachfragen. |
Dem Benutzer des Schlüssels fehlt das Recht „Programme ausführen“ | Die Rolle des Actor-Users darf keine Programme starten. | Unter Admin › Berechtigungen der Rolle in der App Automationen „Programme über einen API-Schlüssel ausführen“ geben. |
Die App Automationen ist in diesem Mandanten nicht aktiv | Programme laufen über die App Automationen. | Die App im Mandanten einschalten lassen. |
Fehler: Unbekannte Werkzeuge … | Das Programm nennt in werkzeuge einen Namen, den der Key nicht erreicht. | Mit search_tools nach dem richtigen Namen suchen, Rechte und Filter an der Adresse prüfen. |
Cannot read properties of undefined im Programm | Das Werkzeug wird im Programm mit Punkt statt Unterstrich aufgerufen. | Im Programm syncore.crm.konto_list(…), in werkzeuge dagegen crm.konto.list. |
Lauf Abgebrochen mit Grund cpu, zeit oder aufrufe | Das Programm rechnet zu lange, läuft länger als 60 Sekunden oder ruft mehr als 200 Werkzeuge auf. | Weniger Schleifen, Arbeit auf mehrere Läufe verteilen. Grenzen: So arbeitet der Code-Mode. |
| Lauf Wartet auf Freigabe | Am Key ist unter Programme freigeben eine Person eingetragen. | Die Person gibt frei: Programme von Agenten freigeben. |
Bevor du beginnst
Wer einen eigenen MCP-Client baut: Bei moderner Protokollversion müssen die Header MCP-Protocol-Version, Mcp-Method und bei tools/call Mcp-Name zum Inhalt passen, sonst kommt 400 mit Code -32020. Eine nicht unterstützte Version beantwortet SynCore mit 400, Code -32022 und der Liste der unterstützten Versionen.