Find your symptom in the first column. Each row is a single cause, ordered by how often it turns out to be the one.
| Symptom | Cause | Fix |
|---|---|---|
| 401 Unauthorized | Wrong username or password, or the account password was used instead of the Application Password. | Copy the Application Password again from the user’s profile, or create a new one. Spaces in it do not matter. |
| 401 on a site without HTTPS | WordPress does not accept Application Passwords over plain HTTP. | Put the site behind a certificate. |
| 401 with a correct password | The host strips the Authorization header before PHP sees it. Common on Apache with CGI or FastCGI. |
Add to .htaccess, before the WordPress rules: RewriteCond %{HTTP:Authorization} ^(.*) and RewriteRule ^(.*) - [E=HTTP_AUTHORIZATION:%1]. Or ask the host. |
| 401 with a correct password | A security plugin has disabled Application Passwords or REST authentication. | Find the setting in that plugin and allow it for this user. |
403 wpvis_forbidden on connect |
The user cannot edit_posts, so the tool catalog is refused. Subscribers and customers cannot connect. |
Give the user Author, Editor or Administrator, as the work needs. |
403 wpvis_forbidden on one call |
That ability needs a capability the user lacks: settings, 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/ |
REST is blocked by a firewall or plugin, or permalinks are not set. | 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 |
The assistant is paused. | Resume from Settings, or wp visibility agent resume. |
| 429 | The hourly write limit for this user and client was reached. | Wait, or raise Assistant write limit (per hour). |
| Connected, but few tools | Tools follow enabled modules and abilities. Redirects, internal linking and the approval ability are off by default. | Turn on the module you need. Leave approval off unless you mean it. |
| “No authentication method configured” | The bridge started without its environment variables. | Set WP_API_URL, WP_API_USERNAME and WP_API_PASSWORD in the block, as printed by wp visibility mcp-config. |
| The bridge connects but finds no tools, or 404s | WP_API_URL is the bare site address. The bridge then looks for an older plugin’s route. |
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, or a client that supports headers. Claude Desktop, ChatGPT. |
npx not found, or the bridge exits at once |
Node.js is missing or older than 22 on the computer running the client. | 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/mcpA JSON list of tools means the site side is fine and the problem is in the client’s configuration. 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.