Most connection problems come from the address, the key or a switch on the site. Start with the error your app shows, then check MazeGraph → Activity → Plugin logs with the From MCP filter: a refused request is usually recorded there with a code. For how connections work, see MCP security and access.
Errors and fixes
| What you see | Likely cause | What to do |
|---|---|---|
404 or “route not found” |
The server is off, the MCP module is switched off, or the app uses the other server’s address. | Check Turn on the MCP server in Settings → MCP and the MCP module in Tools → Extensions. Copy the Address to give your app again: it changes when Server switches between MazeGraph’s own server and the MCP Adapter. |
| No address on the MCP screen | Server is set to The MCP Adapter plugin, but the adapter is not installed, not active or older than 0.7.1. | Install or update the MCP Adapter, or choose Automatic or MazeGraph’s own server. |
401 or “Authentication required” |
The Authorization header is missing, mistyped or uses a revoked key. Activity shows mcp_auth_required or mcp_auth_failed. |
Regenerate the key and paste the new setup text in full. Some apps need a restart to read a changed config file. |
401 with “This password only works for the MazeGraph MCP endpoint” |
The key is being used on another address, for example the plain WordPress REST API. | Use the MCP address from the MCP screen. Connection passwords work nowhere else. |
403 |
The account is not an administrator (mcp_forbidden), or the request came from a web page on another site. |
Create the connection while signed in as an administrator. Connect from a desktop app or terminal, not from a web page. |
429 Too Many Requests |
The account sent more than 120 requests in a minute. | Wait for the time in Retry-After. If an app loops on the same tool, check what it was asked to do. |
| “Unsupported protocol version” | The app asked for an MCP revision MazeGraph does not serve. | Update the app. MazeGraph serves 2026-07-28, 2025-11-25, 2025-06-18 and 2025-03-26. |
| An older app connects to the MCP Adapter but fails at once | The app speaks only revision 2025-03-26, which the adapter does not serve. | Choose MazeGraph’s own server under Server. |
| New connection is unavailable | Application Passwords are off. WordPress offers them only over HTTPS or on a local site; on multisite, MazeGraph must be network-activated. | Serve the site over HTTPS, or network-activate MazeGraph. The MCP screen names the reason. |
| Every tool call is refused | Allow tool use is off for the whole site, which stops tools in the chat and over MCP alike. | Turn it on in Settings → General → Availability. See General settings. |
| A tool you expected is missing | The tool may not be eligible for this MCP server, may be switched off in Tools → Tools, may belong to an inactive module, or its permission check may fail. Activity may show mcp_tool_unavailable. |
Check Tools available over MCP and the server selected in Settings → MCP. MazeGraph’s own server offers eligible enabled read tools; neither MCP path offers MazeGraph writes. |
| claude.ai or ChatGPT cannot add the server | These hosted apps sign in with OAuth, which MazeGraph does not offer yet. | Use a developer app such as Claude Code, Cursor, VS Code or Codex. |
Still stuck
Copy the safe details from Settings → About → Installation diagnostics, note the app and its exact error, and ask on the support page. Never share the connection key or the Authorization header.