Zusätzliches Menü

Holen Sie sich MemberPress noch heute! Lassen Sie sich für die Inhalte, die Sie erstellen, bezahlen! MemberPress jetzt kaufen

MemberPress MCP-Fehler und Fehlerbehebung

Der MemberPress AI Foundation MCP-Server gibt strukturierte Fehlermeldungen aus, wenn eine Anfrage die Authentifizierung nicht besteht, ein Ratenlimit überschreitet, nicht über den erforderlichen Geltungsbereich oder die erforderlichen Funktionen verfügt oder während einer Pause bei destruktiven Schreibvorgängen eingeht. Jeder Fehler enthält einen Code, den ein KI-Client oder Entwickler zuordnen kann.

Dieses Nachschlagewerk listet die vom MCP-Server ausgegebenen Fehlercodes auf, zeigt auf, wodurch die einzelnen Fehler ausgelöst werden, und erläutert, wie sie behoben werden können. Ein Abschnitt zur Fehlerbehebung behandelt die Fehlerarten, die bei der Ersteinrichtung am häufigsten auftreten.

Form der Fehlerantwort

Der Server gibt Fehler auf zwei Ebenen zurück, die unterschiedlich gestaltet sind. Für eine zuverlässige Fehlerbehandlung ist es unerlässlich, das richtige Feld zu identifizieren.

Fehler auf der Transportschicht werden vor der JSON-RPC-Verarbeitung abgelehnt – Authentifizierungsfehler und nicht zugeordnete Routen. Sie verwenden das WordPress-REST-Fehlerformat mit einer Zeichenfolge Code und einen HTTP-Status unter data.status:

{
  "code": "auth_required",
  "message": "Autorisierungs-Header erforderlich.",
  "data": { "status": 401 }
}

Fehler in der Werkzeugschicht finden nach der Authentifizierung während der Tool-Bereitstellung statt – die Sicherheitsschicht und die Berechtigungsprüfungen. Sie verwenden das JSON-RPC 2.0-Fehlerschema, bei dem Code ist der generische JSON-RPC-Wert -32603 und die stabile, zuordnungsfähige Kennung lautet data.mp_error_code:

{
  "code": -32603,
  "message": "Destruktive Schreibvorgänge wurden von einem Administrator angehalten. Versuchen Sie es später erneut oder wenden Sie sich an den Standortbetreiber.",
  "data": { "mp_error_code": "WRITES_PAUSED" },
  "request_id": "req_011Cc7Bhv5NZnRMgQ9Bg2JBo"
}

Spiel am data.mp_error_code, nicht Code. Jeder Fehler in der Werkzeugebene liefert dasselbe Ergebnis -32603; nur mp_error_code zeichnet sie aus. Das request_id ist pro Aufruf eindeutig – nützlich für den Support, jedoch niemals zum Abgleich.

Fehlerkategorien im Überblick

KategorieBezeichnerEbene
Authentifizierungauth_required und Token-FehlerVerkehr (data.status: 401)
Route deaktiviert oder Permalinksrest_no_routeVerkehr (data.status: 404)
Umfang und LeistungsfähigkeitSCOPE_INSUFFICIENT, FÄHIGKEIT_UNZUREICHENDWerkzeug (-32603 + mp_error_code)
SicherheitsschichtWRITES_PAUSED, BESTÄTIGUNG_UNGÜLTIGWerkzeug (-32603 + mp_error_code)
RatenbegrenzungRATE_LIMITED, öffentlich, AnmeldungVerschiedenes – siehe Fehler bei der Ratenbegrenzung
ValidierungValidierungsfehlerWerkzeug (-32603 + mp_error_code)
Ressource und ZustandBenutzer nicht gefunden, doppelte_Benutzernamen, bereits erstattetdie *_nicht_gefunden* FamilieWerkzeug (-32603 + mp_error_code)
Im Abspannnicht genügend_Credits, credits_unavailableNicht über MCP-Tools erreichbar – siehe unten

Fehler bei der Authentifizierung

Der Server überprüft bei jeder Anfrage die Anmeldedaten. Für alle wichtigen MCP-Routen ist ein Bearer-Token oder eine Basic-Authentifizierung erforderlich.

Eine Anfrage mit kein „Authorization“-Header wird auf der Transportschicht abgelehnt:

{
  "code": "auth_required",
  "message": "Autorisierungs-Header erforderlich.",
  "data": { "status": 401 }
}
AuslöserCodeNachricht
Keine Anmeldedatenauth_required“Autorisierungs-Header erforderlich.”
Fehlerhafter Header (nicht „Bearer“ oder „Basic“)auth_required“Bearer- oder Basic-Authentifizierung erforderlich.”
Abgelaufenes Tokentoken_expired“Das Token ist abgelaufen.”
Token wurde widerrufen oder ist nicht vorhandenauth_required“Ungültiges oder widerrufenes Token.”

Ein abgelaufenes Token gibt einen eindeutigen Code zurück. Ein widerrufenes Token und ein Token, das nie existiert hat, sind absichtlich nicht unterscheidbar — Bei der Token-Abfrage werden widerrufene Zeilen herausgefiltert, sodass aus der Antwort nicht hervorgeht, ob ein bestimmtes Token jemals existiert hat.

401 Antworten auf dem MCP-Pfad enthalten eine WWW-Authenticate Kopfzeile mit dem genauen Wert Bearer realm="mcp", resource_metadata="", und der Header wird über CORS offengelegt. Die OAuth-Endpunkte lassen ihn bewusst weg.

Beschluss: Erstellen Sie über den Assistenten ein neues Token oder stellen Sie die Verbindung des Clients erneut her, um den OAuth-Ablauf erneut auszuführen. Vergewissern Sie sich, dass das Token nicht widerrufen wurde auf der Mit MCP verbundene Clients tab.

Fehler bei Umfang und Leistungsfähigkeit

Zwei verschiedene Gateways lehnen einen Tool-Aufruf ab, nachdem die Authentifizierung erfolgreich war. Beide werden als Fehler auf Tool-Ebene angezeigt.

Scope-Gate. Jedes Tool gibt einen erforderlichen Gültigkeitsbereich an. Der Server gleicht diesen vor der Weiterleitung mit den dem Token gewährten Gültigkeitsbereichen ab. Eine schreibgeschützte Verbindung, die memberpress_create_member scheitert an dieser Hürde.

Fähigkeitsprüfung. Jedes Schreib-Tool gibt zudem die WordPress-Fähigkeit an, die es benötigt – zum Beispiel Benutzer anlegen, Benutzer bearbeiten, delete_users, oder manage_options. Der Server überprüft vor der Weiterleitung die Berechtigung des Token-Inhabers. Ein vollständig-ein Scope-Token, das einem Benutzer gehört, ohne Benutzer anlegen Es ist immer noch nicht möglich, Mitglieder anzulegen.

Die Gatter werden der Reihe nach abgearbeitet – zuerst das Scope – und geben dann ein Ergebnis zurück eindeutige Codes:

Tormp_error_codeNachricht
UmfangSCOPE_INSUFFICIENTDer erforderliche Bereich "%s" ist für dieses Token nicht gewährt.
FähigkeitFÄHIGKEIT_UNZUREICHENDUnzureichende Berechtigungen für dieses Tool. Der Benutzer muss über "%s" verfügen.

Beide verwenden die Hüllkurve der Werkzeugebene — -32603 mit der stabilen Kennung in data.mp_error_code:

{
  "code": -32603,
  "message": "Unzureichende Berechtigung für dieses Tool. Der Benutzer muss über die Berechtigung \"create_users\" verfügen.",
  "data": { "mp_error_code": "CAPABILITY_INSUFFICIENT" },
  "request_id": "req_..."
}

Beschluss:

  • Fehler bei der Reichweitenmessung: Die Verbindung benötigt eine umfassendere Berechtigung. Widerrufen Sie diese und richten Sie eine neue Verbindung mit den erforderlichen Schreibberechtigungen ein. Die Zugriffsobergrenze muss auf „Vollzugriff“ gesetzt sein, damit neue Verbindungen Schreibberechtigungen erhalten können;
  • Fehler bei der Leistungsfähigkeit: Dem WordPress-Benutzer hinter dem Token fehlt die erforderliche Rollenberechtigung. Melden Sie sich als Benutzer mit dieser Berechtigung an oder erteilen Sie dem Benutzer die Berechtigung.

Das ist wichtig: Verbindungen mit Anwendungspasswort sind immer schreibgeschützt. Jedes Schreib-Tool scheitert bei einer Verbindung mit Anwendungspasswort grundsätzlich an der Bereichsprüfung. Verwenden Sie für Schreibvorgänge eine OAuth-Verbindung.

Fehler in der Sicherheitsschicht

Die Sicherheitsmaßnahmen für Agenten führen zu eigenen Fehlern auf der Tool-Ebene. Die Leitfaden zu Sicherheitsmaßnahmen für Mitarbeiter erläutert die Maßnahmen; in diesem Abschnitt werden ihre Ablehnungen aufgeführt.

WRITES_PAUSED

Der Kill-Switch unterbricht jeden destruktiven Schreibvorgang. Solange er aktiv ist, lehnt der Server die destruktiven Tools mit folgender Meldung ab: WRITES_PAUSED — unabhängig vom Geltungsbereich der Verbindung und selbst dann, wenn der Aufruf ein gültiges Bestätigungstoken enthält.

Die Ablehnung richtet sich gegen die Erster, unverbindlicher Anruf: Die *Vorschau* eines destruktiven Tools wird blockiert, nicht nur dessen Ausführung. Der Kill-Switch sperrt den gesamten destruktiven Schreibpfad, sodass im angehaltenen Zustand nicht einmal ein Bestätigungstoken erzeugt werden kann. Lesetools funktionieren weiterhin.

{
  "code": -32603,
  "message": "Destruktive Schreibvorgänge wurden von einem Administrator angehalten. Versuchen Sie es später erneut oder wenden Sie sich an den Standortbetreiber.",
  "data": { "mp_error_code": "WRITES_PAUSED" },
  "request_id": "req_011Cc7Bhv5NZnRMgQ9Bg2JBo"
}

Beschluss: Ein Administrator deaktiviert den Kill-Switch über den Mit MCP verbundene Clients Registerkarte. Die Pause ist eine absichtliche administrative Maßnahme; überprüfen Sie, warum sie ausgelöst wurde, bevor Sie das Schreiben fortsetzen.

BESTÄTIGUNG_UNGÜLTIG

Destruktive Tools erfordern einen Ablauf mit zwei Aufrufen: Der erste Aufruf gibt eine Vorschau sowie ein einmalig verwendbares Bestätigungstoken zurück; der zweite Aufruf übergibt das Token im bestätigen. Parameter. Drei unterschiedliche Ursachen führen zum gleichen Ergebnis BESTÄTIGUNG_UNGÜLTIG Fehler — Aus der Meldung geht nicht eindeutig hervor, was genau passiert ist:

UrsacheDetail
Token abgelaufenDas Token ist älter als das 60-Sekunden-Fenster.
Token wurde bereits verwendetToken sind nur einmal verwendbar
Die Argumente haben sich geändertDas Token ist an genau dieses Werkzeug, diese Argumente und diesen Benutzer gebunden
{
  "code": -32603,
  "message": "Das Bestätigungstoken ist ungültig, abgelaufen oder die Argumente haben sich geändert. Rufen Sie das Tool ohne `confirm` auf, um eine neue Vorschau und ein neues Token zu erhalten.",
  "data": { "mp_error_code": "CONFIRMATION_INVALID" },
  "request_id": "req_011Cc7AK3jF4SA4VLs3qsmBD"
}

Beschluss: das Tool erneut aufrufen, ohne bestätigen. um eine neue Vorschau und ein neues Token zu erhalten, und bestätigen Sie dies dann innerhalb von 60 Sekunden mit denselben Argumenten. Da ein Code drei Ursachen abdeckt, sollte ein Client zur Fehlerbehebung die Vorschau erneut ausführen, anstatt zu versuchen, zu diagnostizieren, welche Schutzmaßnahme ausgelöst wurde.

Der Absturz ist beabsichtigt. Eine bloße „Bestanden/Nicht bestanden“-Meldung gibt keinen Aufschluss darüber, ob ein bestimmtes Token jemals existiert hat, und die Behebung des Problems ist in jedem Fall identisch: Führen Sie die Vorschau erneut aus.

Die Antwort lautet: error.data hat eine Grund Feld neben dem unveränderten Code auf oberster Ebene mit zwei Werten: abgelaufen_oder_verwendet (Das Token wurde nicht gefunden – abgelaufen, bereits verbraucht oder bewusst nicht ausgegeben; diese Einträge bleiben ausgeblendet) und arguments_changed (Das Token war gültig, aber die Anfrage wich von der Vorschau ab – führen Sie die Vorschau erneut aus und bestätigen Sie das neue Token).

Fehler bei der Ratenbegrenzung

Unabhängige Ratenbegrenzungen schützen den Server, und Die Antwortkurve unterscheidet sich je nach Endpunkt — der authentifizierte MCP-Endpunkt gibt keine Antwort zurück 429 überhaupt nicht.

OberflächeGrenzeAntwort
Authentifizierter MCP-Endpunkt120 Anfragen pro Minute pro Token (Standard; konfigurierbar von 1 bis 1000) – wird auf der Registerkarte „MCP-Einstellungen“ festgelegt, wo die Ratenbegrenzung auch vollständig deaktiviert werden kannJSON-RPC-Fehler bei HTTP 200 — Code -32029, mp_error_code: RATE_LIMITED
Öffentlicher MCP-Endpunkt60 Anfragen pro Minute pro IP-Adresse (fest)HTTP 429 mit Retry-After: 60
OAuth /registrieren60 Registrierungen pro Stunde pro IP-AdresseHTTP 429 mit Retry-After: 3600

Die Begrenzung des authentifizierten Endpunkts wird innerhalb des JSON-RPC-Envelopes angezeigt, nicht als HTTP-Fehler:

{"jsonrpc":"2.0","id":1,"error":{"code":-32029,"message":"Ratenlimit überschritten.","data":{"mp_error_code":"RATE_LIMITED"}}}

Der öffentliche Endpunkt gibt einen einfachen JSON-RPC-Fehlertext mit seinem 429:

{"jsonrpc":"2.0","error":{"code":-32000,"message":"Ratenlimit überschritten. Bitte versuchen Sie es in einer Minute erneut."}}

Der Registrierungs-Endpunkt gibt einen OAuth-konformen Body mit folgenden Angaben zurück: 429:

{"error":"too_many_requests","error_description":"Zu viele Client-Registrierungen von dieser IP-Adresse. Bitte versuchen Sie es in einer Stunde erneut."}

Anmerkung: Es werden keine Endpunkte gesendet X-RateLimit-Limit oder X-RateLimit-Remaining Header. Die einzigen Header zur Ratenbegrenzung sind die Wiederholversuch nach die oben angegebenen Werte.

Beschluss: Warten Sie, bis das Fenster zurückgesetzt wird. Für den authentifizierten Endpunkt führen Sie einen Abgleich mit mp_error_code: RATE_LIMITED — a 200 Status bedeutet nicht gleich Erfolg – und halte mindestens eine Minute Abstand. Respekt Wiederholversuch nach wohin gesendet. Bei anhaltend hohem Datenvolumen sollten Sie Batch-Anfragen verwenden oder die Abfragehäufigkeit reduzieren.

Validierungsfehler

Validierungsfehler sind Fehler auf der Tool-Ebene: -32603 mit mp_error_code: validation_error. Die Nachricht Das erklärt das Problem bereits an sich – es nennt den abgelehnten Wert und listet, sofern ein Vokabular gilt, die zulässigen Werte auf. Wenn man beispielsweise einen Webhook mit einem unbekannten Ereignis erstellt, wird Folgendes zurückgegeben:

Unbekannte Ereignisse: „member-added“. Bekannte Ereignisse: „transaction-completed“, ...

Schreibwerkzeuge überprüfen die Argumentvokabulare anhand ihrer Schemata, und veraltete Werte werden mit der zulässigen Aufzählung abgelehnt. Coupon-Werkzeuge sind das dokumentierte Beispiel: discount_mode akzeptiert Standard oder erste Zahlungund rabatt_type akzeptiert Prozent oder Dollar. Die bisherigen Werte erste, alleund flach werden abgelehnt.

Beschluss: Korrigieren Sie die Eingabe wie in der Meldung beschrieben – oder lesen Sie die Anleitung des Tools inputSchema in Tools/Liste — dann erneut mit kanonischen Werten senden. Versuchen Sie es nicht erneut mit denselben Argumenten.

Ressourcen- und Systemfehler

Über die Validierung hinaus geben die Tools auf den Aufrufer bezogene Fehlercodes zurück, wenn eine Anfrage zwar korrekt formatiert ist, aber nicht auf den aktuellen Zustand der Website angewendet werden kann. Diese folgen derselben Tool-Ebene-Hülle (-32603 + mp_error_code), und in ihren Nachrichten wird der Grund direkt genannt:

CodeAuslöser
Benutzer nicht gefundenDas angegebene Mitglied oder der angegebene Benutzer existiert nicht.
*_nicht_gefunden* FamilieDie angegebene Ressource (Transaktion, Abonnement, Webhook usw.) existiert nicht.
doppelte_BenutzernamenErstellung eines Benutzerkontos mit einem bereits vergebenen Benutzernamen
bereits erstattetEin Rückerstattungsversuch für eine Transaktion, die bereits erstattet wurde
memberpress_not_activeDas MemberPress-Plugin ist nicht aktiv
Selbstlöschung abgelehntdelete_member Ausgerichtet auf den aufrufenden Benutzer – das Löschen des Kontos, das hinter dem aktuellen Token steht, würde die Sitzung beenden. Die Selbstprüfung wird zuerst ausgeführt und hat daher Vorrang vor dem Admin-Guard.
admin_delete_refuseddelete_member die sich an jeden Nutzer mit dem manage_options Funktionalität. Setzen Sie die Berechtigungen des Benutzers im WordPress-Adminbereich zunächst herab, falls die Löschung beabsichtigt ist.

Beschluss: Es handelt sich hierbei um Dauerzustände und nicht um vorübergehende Fehler – überprüfen Sie die referenzierte Ressource (oder den Status der Website) und korrigieren Sie die Anfrage. Ein Wiederholungsversuch ohne Änderungen kann nicht erfolgreich sein.

Echte interne Fehler — Speichern fehlgeschlagen, Löschvorgang fehlgeschlagen, db_error — sind bewusst allgemein gehalten, damit keine Details der Speicherebene an die Clients weitergegeben werden. Ein Client, der eine solche Meldung erhält, kann den Vorgang lediglich zu einem späteren Zeitpunkt erneut versuchen oder den Fehler dem Website-Administrator melden.

Kreditfehler – über MCP nicht erreichbar

Vorschau-Aufrufe durchlaufen bei Routenfehlern dieselbe Zulassungsliste wie die Live-Ausführung und weisen dieselben mp_error_code — Ein Tool darf in seiner Vorschau keinen internen Fehler preisgeben, der bei der Live-Ausführung verborgen bliebe.

Die Ausnahmeliste des Servers enthält zwei kreditrelevante Codes: nicht genügend_Credits und credits_unavailable. Kein MCP-Tool verbraucht AI-Credits, und der MCP-Server ruft keine Credit-Methode auf. Die Codes sind vorhanden, damit nachgelagerte Dienste Credit-Fehler über die JSON-RPC-Antwort weiterleiten können; kein Aufrufpfad eines MCP-Tools erzeugt solche Fehler.

Ein Client, der mit den MCP-Tools arbeitet, stößt niemals auf diese Codes. Guthaben wirken sich auf die von Mastermind unterstützten Generierungsfunktionen (z. B. Course Copilot) aus, nicht jedoch auf MCP-Tool-Aufrufe.

Fehlerbehebung bei Einrichtungsproblemen

Fehlerarten, die beim ersten Verbindungsaufbau auftreten, in der Reihenfolge, in der sie bei Benutzern typischerweise auftreten:

  • Der authentifizierte MCP-Endpunkt gibt Folgendes zurück: 404: Permalinks sind auf „Plain“ eingestellt. Die REST-API erfordert „Post name“ oder umfangreichere Permalinks;
  • Der öffentliche MCP-Endpunkt gibt Folgendes zurück: 404 (rest_no_route): Der öffentliche Katalog ist deaktiviert. Wenn er deaktiviert ist, wird die Route nicht eingebunden, sodass jede Anfrage rest_no_route — Die Existenz des Endpunkts wird nicht offengelegt. Aktivieren Sie den Katalog auf dem MCP-Einstellungen tab;
  • Der Endpunkt gibt Folgendes zurück: 401 (auth_required) in einem Browser: erwartetes Verhalten. Das 401 bestätigt, dass der Endpunkt aktiv ist; der Browser enthält keinen „Authorization“-Header;
  • Claude Desktop zeigt den Anschluss an, aber keine Werkzeuge: Die OAuth-Genehmigung wurde nicht abgeschlossen oder die Verbindung wurde widerrufen. Öffnen Sie den Konnektor und stellen Sie die Verbindung erneut her;
  • Schritt=Startfehler während der Verbindung mit Claude Desktop: Die OAuth-Registrierung ist auf 60 Versuche pro Stunde und IP-Adresse begrenzt. Warten Sie, bis das Zeitfenster zurückgesetzt ist, und versuchen Sie es erneut;
  • Ein Client eines Drittanbieters kann sich nicht über OAuth registrieren (invalid_redirect_uri): Der Endpunkt für die dynamische Registrierung akzeptiert nur Umleitungs-URIs, die auf der Zulassungsliste stehen (die bekannten KI-Clients). Ein Client, dessen Umleitungs-URI nicht auf der Zulassungsliste steht, wird bei /registrieren;
  • Ein erwartetes Werkzeug fehlt in Tools/Liste: Das Tool gehört zu einem inaktiven Add-on. Add-on-Tools werden nur registriert, solange ihr Add-on aktiv ist. Der Aufruf eines nicht registrierten Tools führt zum Standard-JSON-RPC-Fehler „unknown-method“;
  • Im Assistenten fehlen die Kontrollkästchen: Die Zugriffsobergrenze ist auf „Nur Lesen“ festgelegt. Der Assistent blendet Schreibbereiche aus und zeigt einen Hinweis an. Erhöhen Sie die Obergrenze für die MCP-Einstellungen tab;
  • Ein destruktives Tool gibt eine Vorschau zurück, anstatt den Befehl auszuführen: erwartetes Verhalten. Destruktive Tools erfordern den Bestätigungsablauf mit zwei Aufrufen. Übergeben Sie das zurückgegebene Token an die bestätigen. Parameter innerhalb von 60 Sekunden.

Leitfaden zur Fehlerbehandlung

  • Spiel am data.mp_error_code bei Fehlern in der Werkzeugschicht und bei Code plus data.status auf Fehler auf der Transportschicht. Es darf niemals ein Abgleich mit dem bloßen -32603;
  • auth_required / 401: Führen Sie eine erneute Authentifizierung durch. Versuchen Sie es nicht erneut mit denselben Anmeldedaten; wiederholte Fehlversuche lösen die Brute-Force-Sperre aus;
  • SCOPE_INSUFFICIENT / FÄHIGKEIT_UNZUREICHEND: Nicht erneut versuchen. Für die Verbindung ist eine Berechtigung mit größerem Geltungsbereich erforderlich, oder der hinter dem Token stehende Benutzer benötigt die fehlende WordPress-Berechtigung – ein erneuter Versuch kann nicht erfolgreich sein;
  • WRITES_PAUSED: Nicht automatisch erneut versuchen. Ein Administrator hat zerstörerische Schreibvorgänge absichtlich angehalten; den Status dem Benutzer anzeigen;
  • Validierungsfehler: Korrigieren Sie die Eingabe wie in der Meldung beschrieben und senden Sie sie dann erneut. Versuchen Sie nicht, dieselben Argumente erneut zu verwenden – dieselbe Eingabe führt zur gleichen Ablehnung;
  • BESTÄTIGUNG_UNGÜLTIG: Starten Sie den Ablauf mit zwei Anrufen ab dem Vorschau-Anruf neu. Ein Code deckt drei Ursachen ab, führen Sie daher die Vorschau erneut aus, anstatt zu diagnostizieren, welche Ursache ausgelöst wurde. Speichern Sie Bestätigungs-Token niemals im Cache;
  • Ratenbegrenzungen: Zurückziehen. Der authentifizierte Endpunkt signalisiert RATE_LIMITED innerhalb eines HTTP 200; die öffentlichen und Registrierungs-Endpunkte geben Folgendes zurück 429 mit Wiederholversuch nach. Respekt Wiederholversuch nach sofern gesendet; andernfalls mindestens eine Minute warten.
War dieser Artikel hilfreich?

Verwandte Artikel

Computerfrau

Holen Sie sich MemberPress noch heute!

Lassen Sie sich für die von Ihnen erstellten Inhalte bezahlen.