Skip to content

An MCP app cannot connect

Updated View as Markdown

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.

Was this page helpful?

Your feedback helps us improve these docs.

Documentation

Type to search…

↑↓ navigate↵ selectEsc close