MCP error codes and how to fix them

This list of MCP error codes covers the errors mcp-core and the AddoCore license server return: license check responses, HTTP status codes on the MCP endpoint, download errors and messages from tool calls. Each entry gives the exact text, what triggers it and the fix. Messages appear in the container logs, in Claude, or both.

Which MCP error codes does the license check return?

The license check endpoint returns three error codes. You see them in docker logs mcp-core as Check failed status=…. None of them overwrite the last good license answer, so the 96-hour license grace period keeps your tools running while you fix the cause.

mcpte_invalid_body (HTTP 400)

“Request body is missing required fields.” The request lacked the license key or the instance id. This points at the mcp-core build, not your license. Run ./mcp-update.sh to get a current version.

mcpte_signature_invalid (HTTP 401)

“Request signature verification failed.” Each check is signed with a secret derived from LICENSE_KEY. The reason is one of three: signature_mismatch, timestamp_out_of_range or nonce_reused. Check that LICENSE_KEY in .env matches the key in My Account → MCP Self-hosted exactly. A timestamp error means the server clock is more than 5 minutes off; enable time sync on the host.

mcpte_rate_limited (HTTP 429)

“Too many requests. Please try again later.” By default AddoCore accepts 10 checks per license key per hour and 60 per IP address per hour. The response carries a retry_after value in seconds until the window resets. This happens when you run refresh-license in a loop or several installs share one key. Stop the repeated refreshes; it clears by itself within the hour.

What do MCP error codes for license rejections mean?

A rejection is a valid answer with valid: false. Unlike the MCP error codes above, it blocks tools at once, with no grace period.

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

The key is unknown, revoked or suspended. A suspended license usually follows a renewal that stayed unpaid for 7 days; see MCP license renewal. Otherwise compare the key in .env with My Account.

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

A new instance id checked in while the activation limit was already used. This happens on a new server or after deleting ./state. Release the old activation on the Advanced tab of the license, then run docker exec mcp-core npm run refresh-license.

Which MCP error codes appear when tools are blocked?

When the license blocks tools, Claude still sees them, but every call returns one of these MCP error codes as text:

• “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).” No check has succeeded yet. If the log also says LICENSE_ENDPOINT or LICENSE_KEY not set, the .env is incomplete.
• “License check failed for longer than the grace period allows (last successful check: …).” The server has not reached AddoCore for more than 168 hours. Check outbound HTTPS and firewall rules.
• “This tool is temporarily unavailable due to a license issue. Contact support if this persists.” The fallback when no specific message is available.

Ask Claude to run mcp_status in any of these cases. It works in every license state.

Which HTTP status codes does the MCP endpoint return?

The MCP endpoint (/mcp, or /sse for legacy clients) returns these status codes as its MCP error codes at HTTP level:

• 401 {"error":"Unauthorized"} with WWW-Authenticate: Bearer realm="MCP Core": the token matches no seat. mcp-core accepts it as Authorization: Bearer, in x-api-key, api-key, apikey, api-token, x-auth-token or x-access-token, or as ?token=. A new or regenerated token only works after the next license check, so run a refresh first. A license without any seat authenticates nobody.
• 404 “Session not found” on /message: a legacy SSE session that no longer exists, usually after a container restart. Reconnect the client.
• 500: an unexpected error. The container log has the details.

With AUTH_STRATEGY=oauth you can also see 401 “Invalid client_id”, 400 “Missing redirect_uri”, 400 invalid_grant (an expired or used code) and 401 invalid_client. See MCP authentication.

What do MCP error codes for rate limits look like?

mcp-core limits tool calls per seat and per add-on to 60 per minute by default. Over the limit, Claude gets “Rate limit exceeded for this tool — try again in 12s.” with the real number of seconds. On a self-hosted install you can change the default with SEAT_RATE_LIMIT_PER_MINUTE in .env, then rerun ./mcp-update.sh.

Errors from the external service are separate from the MCP error codes of mcp-core itself. They read like “WooCommerce [shop-a] API error 401: …”: the service, the store or site id, the HTTP status and the first part of the response. A 401 or 403 there means the API key or application password is wrong or lacks rights. For a Missive 429 the text is “Missive API rate limit hit — retry after …s” followed by Missive’s own documented limits.

Which tool errors point at configuration?

These MCP error codes come from the tools themselves:

• A tool missing from Claude’s list while it is entitled: the log has a line such as “No WooCommerce store is configured … No WooCommerce tools will be registered.” Fill in the variables and restart the container.
• “Multiple WooCommerce stores are configured — pass the “store” parameter.” or “Unknown WooCommerce store …”: ask Claude to name the store id. WordPress uses a “site” parameter, Lightspeed a “store” parameter.
• “WOOCOMMERCE_CONNECTIONS is not valid JSON” or “must be a JSON array”: fix the JSON in .env. The same text exists for WORDPRESS_CONNECTIONS and LIGHTSPEED_CONNECTIONS.
• “MISSIVE_FROM_ADDRESS is not configured — cannot send.”: set it to a verified alias of the Missive account.
• “This looks like a write statement (INSERT/UPDATE/DELETE) but this seat is read-only.”: switch the Database tool to read-write for that seat, and give the database user matching rights.
• “Schema-changing statements (CREATE/DROP/ALTER/TRUNCATE/GRANT/REVOKE) are never allowed through this tool.”: make schema changes directly on the database.
• “Path outside vault is not allowed”: a Brain path points outside VAULT_PATH.

Which MCP error codes can the download return?

The Download button on My Account → MCP Self-hosted can return “This download link is invalid or has expired.” (403), “This license is not currently active.” (403) or “The download is not ready yet. Please try again shortly.” (404). Reload the page for a fresh link, renew the license, or wait for the “bundle ready” email.

Most MCP error codes resolve with three steps: run mcp_status, read docker logs mcp-core, then refresh the license. Next, read MCP diagnostics to understand the state the logs report.