MCP-foutcodes en hoe je ze oplost

Deze lijst met MCP-foutcodes behandelt de fouten die mcp-core en de AddoCore-licentieserver teruggeven: antwoorden op licentiechecks, HTTP-statuscodes op het MCP-endpoint, downloadfouten en meldingen van toolaanroepen. Per item vind je de exacte tekst, wat de fout veroorzaakt en de oplossing. Meldingen verschijnen in de containerlogs, in Claude of op beide plekken.

Welke MCP-foutcodes geeft de licentiecheck?

Het endpoint voor de licentiecheck geeft drie foutcodes. Je ziet ze in docker logs mcp-core als Check failed status=…. Geen ervan overschrijft het laatste goede licentieantwoord, dus de respijtperiode van de licentie van 96 uur houdt je tools draaiend terwijl je de oorzaak oplost.

mcpte_invalid_body (HTTP 400)

“Request body is missing required fields.” Het verzoek miste de licentiesleutel of de instance-id. Dat wijst op de mcp-core-build, niet op je licentie. Draai ./mcp-update.sh voor een actuele versie.

mcpte_signature_invalid (HTTP 401)

“Request signature verification failed.” Elke check wordt ondertekend met een geheim dat is afgeleid van LICENSE_KEY. De reden is een van drie: signature_mismatch, timestamp_out_of_range of nonce_reused. Controleer of LICENSE_KEY in .env exact overeenkomt met de sleutel in Mijn account → MCP Self-hosted. Een timestampfout betekent dat de serverklok meer dan 5 minuten afwijkt; zet tijdsynchronisatie aan op de host.

mcpte_rate_limited (HTTP 429)

“Too many requests. Please try again later.” Standaard accepteert AddoCore 10 checks per licentiesleutel per uur en 60 per IP-adres per uur. Het antwoord bevat een waarde retry_after met het aantal seconden tot het venster reset. Dit gebeurt als je refresh-license in een lus draait of als meerdere installaties één sleutel delen. Stop de herhaalde refreshes; het lost zichzelf binnen het uur op.

Wat betekenen MCP-foutcodes bij afgewezen licenties?

Een afwijzing is een geldig antwoord met valid: false. Anders dan de MCP-foutcodes hierboven blokkeert die tools direct, zonder respijtperiode.

“This license key is not valid or has been revoked.”

De sleutel is onbekend, ingetrokken of opgeschort. Een opgeschorte licentie volgt meestal op een verlenging die 7 dagen onbetaald bleef; zie MCP-licentie verlengen. Vergelijk anders de sleutel in .env met die in Mijn account.

“This license has reached its maximum number of active installations. Release an unused activation from your account to continue.”

Een nieuwe instance-id meldde zich terwijl de activatielimiet al bereikt was. Dat gebeurt op een nieuwe server of na het verwijderen van ./state. Geef de oude activatie vrij op het tabblad Geavanceerd van de licentie en draai daarna docker exec mcp-core npm run refresh-license.

Welke MCP-foutcodes verschijnen als tools geblokkeerd zijn?

Als de licentie tools blokkeert, ziet Claude ze nog wel, maar elke aanroep geeft een van deze MCP-foutcodes als tekst terug:

• “No valid license found yet. Check LICENSE_KEY and LICENSE_ENDPOINT, or wait for the first license check to complete (this happens automatically at startup).” Er is nog geen check geslaagd. Staat er in de log ook LICENSE_ENDPOINT or LICENSE_KEY not set, dan is de .env onvolledig.
• “License check failed for longer than the grace period allows (last successful check: …).” De server heeft AddoCore al meer dan 168 uur niet bereikt. Controleer uitgaand HTTPS-verkeer en firewallregels.
• “This tool is temporarily unavailable due to a license issue. Contact support if this persists.” De terugvalmelding als er geen specifieke melding beschikbaar is.

Vraag Claude in al deze gevallen om mcp_status uit te voeren. Die werkt in elke licentiestatus.

Welke HTTP-statuscodes geeft het MCP-endpoint?

Het MCP-endpoint (/mcp, of /sse voor oudere clients) geeft deze statuscodes als MCP-foutcodes op HTTP-niveau:

• 401 {"error":"Unauthorized"} met WWW-Authenticate: Bearer realm="MCP Core": het token hoort bij geen enkele seat. mcp-core accepteert het als Authorization: Bearer, in x-api-key, api-key, apikey, api-token, x-auth-token of x-access-token, of als ?token=. Een nieuw of vernieuwd token werkt pas na de volgende licentiecheck, dus draai eerst een refresh. Een licentie zonder seats laat niemand binnen.
• 404 “Session not found” op /message: een oude SSE-sessie die niet meer bestaat, meestal na een herstart van de container. Verbind de client opnieuw.
• 500: een onverwachte fout. De containerlog bevat de details.

Met AUTH_STRATEGY=oauth kun je ook 401 “Invalid client_id”, 400 “Missing redirect_uri”, 400 invalid_grant (een verlopen of al gebruikte code) en 401 invalid_client zien. Zie MCP-authenticatie.

Hoe zien MCP-foutcodes voor rate limits eruit?

mcp-core beperkt toolaanroepen per seat en per add-on standaard tot 60 per minuut. Boven die limiet krijgt Claude “Rate limit exceeded for this tool — try again in 12s.” met het echte aantal seconden. Op een zelf gehoste installatie kun je de standaard wijzigen met SEAT_RATE_LIMIT_PER_MINUTE in .env en daarna ./mcp-update.sh opnieuw draaien.

Fouten van de externe service staan los van de MCP-foutcodes van mcp-core zelf. Ze zien eruit als “WooCommerce [shop-a] API error 401: …”: de service, de winkel- of site-id, de HTTP-status en het begin van het antwoord. Een 401 of 403 daar betekent dat de API-key of het applicatiewachtwoord niet klopt of onvoldoende rechten heeft. Bij een Missive-429 is de tekst “Missive API rate limit hit — retry after …s”, gevolgd door de gedocumenteerde limieten van Missive zelf.

Welke toolfouten wijzen op configuratie?

Deze MCP-foutcodes komen van de tools zelf:

• Een tool ontbreekt in de lijst van Claude terwijl er wel een entitlement is: de log bevat een regel als “No WooCommerce store is configured … No WooCommerce tools will be registered.” Vul de variabelen in en herstart de container.
• “Multiple WooCommerce stores are configured — pass the “store” parameter.” of “Unknown WooCommerce store …”: vraag Claude de winkel-id te noemen. WordPress gebruikt een parameter “site”, Lightspeed een parameter “store”.
• “WOOCOMMERCE_CONNECTIONS is not valid JSON” of “must be a JSON array”: herstel de JSON in .env. Dezelfde tekst bestaat voor WORDPRESS_CONNECTIONS en LIGHTSPEED_CONNECTIONS.
• “MISSIVE_FROM_ADDRESS is not configured — cannot send.”: stel deze in op een geverifieerde alias van het Missive-account.
• “This looks like a write statement (INSERT/UPDATE/DELETE) but this connection is read-only.”: zet de Database-tool voor die seat op read-write en geef de databasegebruiker de bijbehorende rechten.
• “Schema-changing statements (CREATE/DROP/ALTER/TRUNCATE/GRANT/REVOKE) are never allowed through this tool.”: voer schemawijzigingen direct op de database uit.
• “Path outside vault is not allowed”: een Brain-pad wijst buiten VAULT_PATH.

Welke MCP-foutcodes kan de download geven?

De downloadknop op Mijn account → MCP Self-hosted kan “This download link is invalid or has expired.” (403), “This license is not currently active.” (403) of “The download is not ready yet. Please try again shortly.” (404) geven. Herlaad de pagina voor een nieuwe link, verleng de licentie, of wacht op de e-mail dat de bundel klaar is.

De meeste MCP-foutcodes los je op in drie stappen: draai mcp_status, lees docker logs mcp-core en refresh daarna de licentie. Lees vervolgens MCP-diagnostiek om de status te begrijpen die de logs melden.