Why Is My AI Assistant Unable to Connect to WordPress MCP?
Diagnose WordPress MCP failures by endpoint, network, credentials, protocol and tool errors. Check Niwa's response before retrying a timed-out write.
An AI assistant can fail to connect to WordPress MCP because it is using the wrong endpoint, cannot reach the site, is not sending a valid credential or speaks an incompatible protocol revision. If discovery already works, the failure may belong to a particular tool or business task rather than the connection itself. Use the first failing step and its response to choose the repair.
Niwa MCP exposes the site’s native operations through an authenticated HTTP route. Start with the endpoint and client example displayed by your actual Niwa installation, then check the running client rather than a configuration file in isolation.
Confirm the URL and the environment
Niwa’s endpoint normally resembles https://example.com/wp-json/niwa-ai/v1/mcp. Copy the displayed URL, including any installation subdirectory. Do not use the homepage, a WordPress login address or another connector’s endpoint.
Check whether the client runs locally or from a cloud service. A site accessible on your laptop may be blocked from another network, protected by staging authentication or available only through a local address. Verify DNS and HTTPS from the environment that actually makes the request.
If the response is homepage HTML, a login form or a security challenge, inspect the redirect and interception layer. Do not describe that HTML response as successful MCP discovery merely because its HTTP status is 200.
Check whether the active process sends the credential
A saved bearer-token variable name does not prove the process has its value. Load the credential privately before starting the client. Restart an existing application after changing its startup environment.
For Niwa, inspect token expiry and revocation in the site’s MCP settings. The account behind the token must remain authorized. If a proxy or hosting rule strips the Authorization header, the client can appear correctly configured while WordPress receives no usable credential.
Niwa can reject conflicting credentials when a bearer header and its alternate token header disagree. Use the supported configuration for your client and avoid maintaining two different credentials for the same request. Share sanitized errors, never the token.
Interpret the response at the layer that produced it
These are useful distinctions for Niwa’s endpoint. Hosting or security software may produce its own responses, so read the response body as well as the status.
| Response | What to investigate |
|---|---|
| 401 from Niwa | Missing, conflicting, expired, revoked or unauthorized credential. |
| 403 from Niwa | The reported origin or operation-specific permission restriction. |
| 405 from Niwa | Wrong HTTP method; the endpoint expects POST. |
| 415 from Niwa | Request Content-Type must be application/json. |
| 400 from Niwa | The specific JSON-RPC, protocol, method or argument problem reported. |
| 200 with a tool error | The connection returned a tool failure; inspect its details. |
A browser GET returning 405 does not tell you whether the bearer token works. An options-reader scope error does not establish that all tools are unavailable. A tool validation failure can be returned within a successful HTTP response.
Resolve protocol mismatches through the client
Niwa supports its current stateless request contract and specified older protocol revisions. The current route validates protocol metadata and corresponding request headers. Older initialization examples cannot simply be mixed with current-revision headers.
Use a compatible client and the site’s configuration example. When a response reports an unsupported version or mismatched metadata, record the client and Niwa versions and the sanitized error. Compare with the current MCP transport documentation.
Do not solve a malformed protocol request by repeatedly generating administrator tokens. Authentication can be valid while request validation fails later.
When discovery works, inspect the failing tool
Request the tool list and inspect the exact input schema. A guessed tool name, string where an integer is required or missing target ID can fail after a successful connection.
For a known Niwa page, get_page uses page_id. For a product or variation, resolve the actual record and use the appropriate operation. Confirm that the relevant plugin and tools are available on this site.
The MCP tools specification separates protocol errors from tool-execution errors. Preserve that distinction when reporting the incident. It prevents a valid connection from being rebuilt to fix a bad argument.
Separate Niwa agent availability from native tools
Niwa’s own model connection and the external MCP credential serve different purposes. Deterministic WordPress operations can work without Niwa’s own model provider connection. A model-dependent agent task may still fail because that separate connection is unavailable.
For an accepted niwa_agent_run task, retain its job ID and retrieve its result. If a write response times out, read the affected record before repeating the request. The server may have saved the change even though the response never reached the client.
Send enough evidence for a targeted repair
Keep the site and environment, connector version, client version, transport, first failing operation and sanitized response. Include the stable job or record ID when applicable. This is enough to distinguish routing, authentication, protocol and execution problems without exposing credentials or customer data.
The Niwa setup guide covers the WordPress settings. Existing owners can use the standalone plugin. Contact Niwa about the failed connection with that evidence and the task you want restored.
