WordPress MCP Connection Troubleshooting, Layer by Layer
WordPress MCP connection troubleshooting for GoBuildWP: find the failing layer, run Connection Doctor, then fix HTTPS, OAuth, headers and permissions.
A missing tool can have several causes: the module never registered, the safety profile is withholding it, the WordPress user lacks the capability, or the client cached an older tool list. They look identical from inside the AI client, which is why the sequence below checks them from the WordPress side instead. Integration health answers the first, the profile screen the second, and a fresh client session the fourth.
Identify the failing layer
Separate transport, authentication, authorization, ability availability, ability execution, and external provider outcomes. A server can be reachable while credentials fail; discovery can work while a write is forbidden; a WordPress update can succeed while email or payment delivery fails.
Record the client and version, endpoint, transport, authentication method, HTTP status, exact error, active safety profile, WordPress user role, and intended ability before changing configuration.
Run Connection Doctor first
From GoBuildWP 1.15.0, Connection Doctor runs from the Diagnostics screen, and an already-connected agent can call it as wppilot/connection-doctor. It checks observable connection conditions - a firewall, Cloudflare, ModSecurity, an Authorization header stripped before WordPress sees it, Application Passwords switched off, OAuth clock skew or a site URL mismatch - and gives the fix for the server it is running on.
It reports what the site can observe about itself. A block that happens before a request reaches WordPress, or a problem inside the client, still needs the client's own error message, so keep that alongside the report.
Connection and authentication
Confirm that the endpoint uses the exact site URL and public HTTPS when the client is remote. Check redirects, TLS, caches, security plugins, reverse proxies, and any layer that strips Authorization headers.
For OAuth, retry the browser flow only after checking the callback and discovery response. For Application Passwords, create a dedicated password, remove whitespace introduced during copying, and revoke obsolete credentials.
- Endpoint answers from the client environment
- HTTPS certificate is trusted
- Authorization headers reach WordPress
- The credential belongs to the intended user
- The client config file is the one actually loaded
Permissions and abilities
If discovery succeeds but a tool is absent, inspect its enabled status, current safety profile, WordPress capability requirement, Pro licence, companion plugin, version floor, and integration health. The live registry is authoritative.
If a tool returns a structured refusal, do not bypass it by enabling Developer Full Access. Fix the missing legitimate requirement or choose a safer workflow.
Chat and external providers
For in-dashboard Chat, confirm that the WordPress AI Client has a configured provider and model and that provider consent is recorded. Provider credentials, quota, regional availability, model capability, attachment support, and network access remain external dependencies.
Keep the exact provider error. A generic GoBuildWP connection test cannot prove the provider accepted a request or retained data according to your policy.
The Diagnostics screen, probe by probe
Run the WordPress MCP connection troubleshooting checks
Open GoBuildWP, Diagnostics. In How do you connect?, pick OAuth, Application Password or Access token, or leave it on Not sure to check all of them, then select Run diagnostics. The site sends real requests to its own MCP endpoints and lists each probe with a result and, where one fails, the fix for the server it is running on. When something needs a second pair of eyes, Copy report for support copies the results as text you can paste into a ticket without exposing a credential.
Read a clean result for what it is. When every probe passes, the screen says so and adds that this is necessary but not sufficient: a firewall or CDN at the edge can still block AI clients by IP address or request signature, and the site cannot see that from inside. If the probes pass and your client still fails, the problem is in front of the site or inside the client, and the symptom picker below the results is the next step.
What each failed probe is telling you
Each probe isolates one layer, so a failure points at a specific fix rather than a general suspicion.
- The web server answered 404 itself: requests to /wp-json/ never reach WordPress. Go to Settings, Permalinks and select Save Changes to rewrite the rules; on nginx the site block needs try_files $uri $uri/ /index.php?$args.
- WordPress answered, but the MCP route is not registered: AI abilities is switched off in Settings, or, if it is on, the plugin did not load completely. Reinstall the release ZIP.
- The MCP endpoint completed a handshake without valid credentials: treat this one as urgent. The probe proves that the endpoint answered a caller it could not identify, not that an unauthorized tool call succeeded, but whatever let that request through may also let one run abilities. Switch AI abilities off, find the plugin that force-authenticates REST requests, then run diagnostics again before switching them back on.
- The site could not reach its own endpoint: hosts and containers often block loopback requests. That does not mean outside clients are blocked; test from the AI client itself before changing anything.
- The Authorization header arrived changed: a proxy or security layer rewrites it, often an HTTP Basic password on a staging site. Exempt the MCP paths from it.
- Application Passwords not accepted: WordPress disables them on a site it does not see as HTTPS, and plugins or code can disable them through the wp_is_application_passwords_available filter. Serve the site over HTTPS (on a development site only, set WP_ENVIRONMENT_TYPE to local), allow them again, or connect with an access token instead.
- OAuth answered 401 without a WWW-Authenticate challenge: a proxy or CDN is removing that header, so clients cannot discover where to sign in. Pass it through unchanged for the OAuth endpoint.
- /.well-known/ answered 404 from the web server: OAuth clients cannot find the authorization server. The server configuration has to pass that path to WordPress.
- The server clock is off: OAuth codes and tokens are judged against it, so sign-in fails with invalid_grant or tokens arrive already expired. Ask the host to enable time synchronisation (NTP).
- WordPress Address and Site Address differ in host or in http and https: a warning, not a certain cause. The issuer and the sign-in page can then disagree, and some clients reject the grant. If OAuth sign-in fails with invalid_grant, give both the same host and https:// under Settings, General (a WordPress installed in its own subdirectory keeps its different path), with a backup first, because a wrong address can lock you out of wp-admin. The result also lists the other invalid_grant causes to rule out.
Troubleshooting by what your AI client shows
Below the results, What do you see in your AI client? offers the closest symptom, filtered to the method you chose. Each answer covers what the server cannot test from inside.
- A registration or sign-in service error (OAuth): the client's automatic registration requests are being blocked or rate-limited before they reach WordPress. Choose your client and select Generate Auth Client ID to skip that step; the ID stays valid until used and is listed in Connected Apps as manually created.
- The login page opens but authorizing loops (OAuth): the consent screen is a wp-admin page and needs the normal login cookie. Finish logging in to WordPress in the same browser, relax cookie or privacy extensions for the site, and let administrators past any maintenance or coming-soon plugin.
- It worked before, now requests fail with 401 (OAuth): the permalink structure changed, which changes the token audience; the access was revoked in Connected Apps; or the site moved to plain HTTP, which turns OAuth off entirely.
- The client connects but shows no GoBuildWP tools: the client is pointing at the wrong address, because the OAuth URL and the Application Password URL are different endpoints, or it has not been restarted to reload its server list.
- The Application Password method fails with 401: the password was revoked, Application Passwords are unavailable, the header is stripped, or a security layer alters the authenticated request.
- An access token is rejected with 401: it was revoked or has expired (the token list labels an expired one), the account that created it can no longer manage GoBuildWP, the value was cut or wrapped when copied, the header lacks the Bearer prefix, or the header is stripped.
Take the client out of the question
The Connect screen's curl example can isolate one request from the AI client. A successful tool list verifies that curl request's endpoint, credential and discovery path. It does not prove the client's network path, callback, negotiated transport or intended ability execution. Compare those requests before changing configuration.
A needs-authentication label is a clue to inspect. Compare it with a named authorized tool result and the client's exact error; a label alone establishes neither success nor failure. Check the endpoint, loaded credential and OAuth behavior for that client build rather than assuming the warning can be ignored.
Questions this guide answers
Is there a built-in connection check?
Yes, from GoBuildWP 1.15.0: Connection Doctor on the Diagnostics screen, also available to a connected agent as wppilot/connection-doctor. It looks for firewalls, Cloudflare, ModSecurity, a stripped Authorization header, disabled Application Passwords, OAuth clock skew and URL mismatches, and says how to fix each on your server.
Where should I start when a connection fails?
Identify the transport and client execution environment, then test reachability there. Hosted remote connectors need public HTTPS; local bridges need their own network route, and stdio requires local WordPress files. Inspect exact errors before changing credentials.
The client authenticates but no tools appear. What is wrong?
Inspect the authorization and availability layers: the safety profile, the abilities you have enabled, or the WordPress user's capabilities. Check what the profile permits and whether the ability is enabled before assuming the connection is broken.
The flow completes but the client still reports it is unauthenticated.
Inspect the returned error, token validity, issuer and resource URLs, and whether Authorization reaches WordPress. Header stripping is one possible cause; do not infer it from the client label alone.
Review noteRequirements and credential methods follow the shipped GoBuildWP source (WordPress 6.9+, PHP 8.0+). Client menus, account plans and third-party behaviour can change; use the installed version and live schema. Our evidence standard.
401: inspect response body, credential expiry or revocation, endpoint and Authorization forwarding. 403: inspect user authority, token scope and site policy. Empty discovery: compare installed registry and enabled dependencies. Stale tools: refresh the client session. Execution failure: retain the exact ability, sanitized arguments and returned error before retrying.
Safe support template: Expected result; actual result; GoBuildWP/WordPress/companion/client versions; reproduction steps; redacted error code; time and timezone. Exclude passwords, keys, cookies and private customer data.