Skip to content
WP Visibility

Connect an assistant

The Assistant Gets 401, 403, 404 or Sees No Tools

Each row matches one symptom to one cause, such as the credential, the user's role, a module, or the transport. Find yours and fix that one.

Updated September 27, 2026

Docs

Find your symptom in the first column. Each row is a single cause.

Symptom Cause Fix
401 Unauthorized Wrong username or password, or the account password was used instead of the Application Password. WordPress shows an Application Password only once, so create a new one in the user’s profile if it was not saved. Spaces in it do not matter (WordPress handbook, checked September 27, 2026).
401 on a site without HTTPS WordPress only offers Application Passwords over HTTPS, unless the site’s environment type is local (WordPress reference, checked September 27, 2026). Put the site behind a certificate.
401 with a correct password In a CGI environment the web server can strip the Authorization header before PHP sees it (REST API FAQ, checked September 27, 2026). On Apache, make sure .htaccess has the line WordPress’s own block includes, after RewriteEngine On: RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}] (WordPress handbook, checked September 27, 2026). Or ask the host.
401 with a correct password A security plugin has disabled Application Passwords (WordPress handbook, checked September 27, 2026). Find the setting in that plugin and allow it for this user.
ability_invalid_permissions or wpvis_forbidden on one call (on the Abilities REST route, 403 with rest_ability_cannot_execute or wpvis_forbidden; WordPress core source, checked September 27, 2026) Any logged-in user can connect and list the tools; each call then checks the user’s capabilities. Settings, site audits, bulk updates, redirects and proposals need an administrator. Use the right ability for the role, or raise the role deliberately.
404 rest_no_route at /wp-json/wp-visibility/mcp The Assistant connection module is off. WP Visibility → Settings → Modules, turn it on.
404 for all of /wp-json/ Permalinks are not set, so the REST API answers only at ?rest_route=/ (REST API handbook, checked September 27, 2026). A firewall or security plugin can also block /wp-json/. Allow /wp-json/ for authenticated users; set a permalink structure under Settings → Permalinks.
405 Method Not Allowed The client sent a GET, usually trying to open a server-sent events stream. The endpoint is POST only. Use a client that speaks streamable HTTP with POST, or the bridge.
agent_paused, or ability_invalid_permissions on every call, reads included The assistant is paused. WordPress hides a permission check’s reason when it runs an ability, so on the MCP endpoint a pause shows as ability_invalid_permissions (WordPress core source, checked September 27, 2026). A role too low for every tool looks the same. Click Resume agent access under Settings → Assistant connection, or run wp visibility agent resume. If it was not paused, see the one-call row above.
rate_limited (429 on the Abilities REST route) The hourly write limit for this user and client was reached. Wait, or raise Assistant write limit (per hour).
A tool returns module_disabled The tool list does not follow modules. Redirect, IndexNow, Link Graph, AI Traffic Lens, import and proposal tools stay listed while their module is off, and refuse with this error. Redirects, IndexNow, Link Graph, AI Traffic Lens and Autopilot are off by default. Turn on that module under WP Visibility → Settings → Modules.
approve-proposal is not in the tool list It is off by default, so the assistant’s tools do not include approving its own proposals. The proposal REST routes still accept any administrator’s credential. Approve in WP Visibility → Review queue.
“No authentication method configured” The bridge started without WP_API_USERNAME or WP_API_PASSWORD, and with no other sign-in method set (bridge source, checked September 27, 2026). Set WP_API_URL, WP_API_USERNAME and WP_API_PASSWORD in the block printed by wp visibility mcp-config, then change WP_API_URL as in the next row.
The bridge connects but finds no tools, or 404s WP_API_URL is the bare site address, which is what wp visibility mcp-config prints. The bridge then looks for the route of the deprecated wordpress-mcp plugin (bridge README, checked September 27, 2026). Use the full endpoint: https://your-site.com/wp-json/wp-visibility/mcp.
The client’s form only asks for a URL and OAuth That form cannot send the Application Password. Use the bridge, as Claude Desktop does, or a client that supports headers. For ChatGPT, see what works today.
npx not found, or the bridge exits at once Node.js is missing, or older than the 22 the bridge’s README requires, on the computer running the client (bridge README, checked September 27, 2026). Install a current Node.js and restart the client.

Test outside the client

A single request with curl separates the site from the client. With the endpoint, username and Application Password:

curl -u 'seo-agent:xxxx xxxx xxxx xxxx xxxx xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  https://your-site.com/wp-json/wp-visibility/mcp

A JSON list of tools means the endpoint and the credential work, and the problem is in the client’s configuration. Any logged-in user gets this list, so a call can still fail on one of the permission rows above. A status code sends you to the table above.

Still stuck

Write to support@wpvisibility.com with the status code, the client, and the curl result. Never include the password.