WordPress MCP Adapter 404: Fix the REST Endpoint

Getting a 404 or rest_no_route when connecting an AI client to the official WordPress MCP Adapter? First find out which layer returned it. An HTML “Not Found” page on /wp-json/ often points toward a URL, rewrite or proxy problem. A WordPress JSON error on /wp-json/mcp/mcp-adapter-default-server means WordPress received the request but the specific route and HTTP method did not match. That may be a wrong address or method, an inactive/incomplete adapter, or a default MCP server disabled by another integration. Do not make the endpoint public or turn off your firewall just to make the 404 disappear.

Fast diagnosis: Confirm the real WordPress Site Address → check the public REST index → distinguish HTML from JSON errors → use the official MCP endpoint and an actual compatible client → inspect whether the default server route is registered → correct only the proven cause. The official MCP Adapter is a WordPress plugin, currently at version 0.7.1 as checked on October 31, 2026. It requires WordPress 6.9+ and PHP 7.4+; those are minimum plugin requirements, not a recommendation to operate on an obsolete PHP release.

If wp-admin still works, the ModelGain Agent Readiness Audit can collect local evidence about whether the MCP Adapter is detected and whether a related REST route is registered. It does not install, enable or repair MCP, authenticate an external client, or guarantee that requests through your CDN will succeed.

First: what should the WordPress MCP Adapter endpoint be?

The official site-owner guide documents the default MCP server at this site-relative path:

https://example.com/wp-json/mcp/mcp-adapter-default-server

Replace example.com with the site’s actual public WordPress REST base URL. The Site Address (URL) is a useful starting point, but the public URL, WordPress filesystem path and WordPress Address (URL) can differ on subdirectory installations. Use the REST index or the WordPress-generated REST URL rather than blindly prepending a directory such as /cms/. If the installation uses plain permalinks or the host does not pass pretty REST URLs correctly, the official guide documents a query-route alternative:

https://example.com/?rest_route=/mcp/mcp-adapter-default-server

Important HTTP-method distinction: MCP over Streamable HTTP uses protocol-specific requests; loading an endpoint with a normal browser GET (or running curl -I, which sends HEAD) is not an authenticated MCP connection test. A 404 can describe an unmatched method as well as an unmatched path. Confirm the available route/method and use the intended MCP client on a controlled environment before declaring the server broken. A response to an unauthorized test can indicate that the route exists without proving the full client handshake succeeds.

1. Classify the response before changing WordPress settings

Check the WordPress REST index through two safe, unauthenticated GET requests. These commands query only the public REST index, not the privileged MCP endpoint, and never send an Application Password:

curl --silent --show-error --max-time 15 --dump-header - \
  https://example.com/wp-json/ --output /tmp/wp-mcp-rest-index.json

curl --silent --show-error --max-time 15 --dump-header - \
  'https://example.com/?rest_route=/' --output /tmp/wp-mcp-rest-query.json

Inspect the returned HTTP status, Content-Type, redirect destination and whether the body looks like the WordPress REST index. Use the correct site base in both URLs. The files are temporary local output for this read-only comparison; store and remove them according to your normal operational policy.

If the basic /wp-json/ root itself fails, use our general WordPress REST API 404 guide for precise rewrite and proxy isolation. Do not duplicate that work by changing settings in the MCP Adapter first. The WordPress REST routes handbook explains why namespace and HTTP method are both part of matching a request.

2. If WordPress returns JSON rest_no_route, check adapter and default-server registration

Open Plugins → Installed Plugins in the correct WordPress installation and confirm that the official MCP Adapter is present, activated and updated from a trusted release. WordPress.org distributes an installable plugin; older tutorials describing a GitHub-only installation route are outdated. A checkout of the GitHub source is not necessarily a complete deployable release and may lack bundled dependencies. The official troubleshooting guide discusses missing Composer/Jetpack autoloaders and recommends installing a packaged release instead of treating source files as a ready-to-install ZIP.

Check the PHP and WordPress versions against the current plugin’s published requirements. The Abilities API is in WordPress core from 6.9 onward; an older WordPress site cannot become compatible just by resaving permalinks. For version/bootstrap concerns follow our Abilities API version-check guide.

For a developer with authorized WP-CLI access to a working WordPress installation, the following read-only inspection checks whether WordPress currently has a default MCP route registered. Run it in the exact vhost’s WordPress path; it does not execute an ability or send credentials to an MCP client:

wp --path=/path/to/wordpress eval '
$routes = rest_get_server()->get_routes();
$key = "/mcp/mcp-adapter-default-server";
echo isset($routes[$key]) ? "Route registered\n" : "Route not registered\n";
'

This is local route-registration evidence, not proof that a remote client will authenticate through the public network or that every expected MCP tool exists. Some deployments register custom MCP server names; check the actual documented server configuration rather than assuming the default name always applies. If the correct route exists locally but your client still fails, look at the request method, public host and auth/proxy path before reinstalling the adapter.

3. A real cause: another plugin can disable the default MCP server

This is why a generic “save permalinks and try again” answer can be wrong. In WordPress MCP Adapter issue #367 (October 3, 2026), a reporter received JSON rest_no_route for the default endpoint after an update and traced the incident to a bundled Elementor MCP integration. Issue #399 explains the mechanism: a component can return false from the mcp_adapter_create_default_server filter, so the adapter never registers its default route and WordPress responds with an ordinary 404.

The issue describes behavior in particular integration/version/settings combinations, including an Elementor 4.3.3 case. Do not interpret this as evidence that every Elementor installation breaks MCP, and do not assume a later patch has or has not landed in your installed version without checking its release notes. It is an important diagnosis when the REST index works but the default route disappears after an update.

Investigate in this order:

1. Record the active WordPress, MCP Adapter, Elementor and other MCP-related plugin versions, plus the time the connection last worked.
2. Inspect whether another active plugin bundles an adapter and whether it has a setting that selects or disables the official default server. Search locally maintained integration code for the documented mcp_adapter_create_default_server filter if you own the code.
3. On a staging replica, compare route registration before and after one controlled integration setting or version change. Maintain a known-good backup and revert the single change if it does not explain the failure.
4. If you confirm a conflict, prefer a supported vendor update/configuration and retest the original client path. Do not blanket-disable Elementor, checkout, security or permission plugins on a production site merely to obtain HTTP 200.

A second GitHub issue #158 reports a rest_no_route failure alongside a missing Composer autoloader, illustrating a different cause with a similar symptom. Source installation faults and filter conflicts should not be conflated.

4. If the pretty path fails but the query-route endpoint works, inspect the web-server layer

If the REST index works only through ?rest_route=/, or if an authorized client reaches the query-style MCP endpoint but not the pretty route, investigate the active WordPress permalink setting and the actual web server or reverse proxy. For meaningful comparison, make the same authorized MCP request to each supported endpoint form: identical HTTP method, body, protocol headers and protected client identity. Never compare an anonymous browser GET on one URL to a fully authenticated POST on the other and infer a rewrite defect. Nginx does not read Apache .htaccess rules; blindly writing an Apache rewrite file cannot repair an Nginx-only deployment. Saving Settings → Permalinks can change rewrite state, so capture the existing configuration and test unrelated pages on staging.

Issue #315 reports a host where an Authorization header arrived through one query-style route but was stripped on a pretty route. That is a separate proxy/authentication fault: the endpoint might exist but cannot authorize the client. If comparing routes, use a purpose-built client with protected credentials rather than embedding a user/password in a URL or shell command. Never print Application Passwords into terminal history, public logs or browser screenshots.

Do not broadly exempt /wp-json/ from your CDN/WAF or change all REST permissions to public. Use a request ID and timestamp to compare the specific reverse-proxy/CDN decision with your server logs, and apply the minimum documented route correction.

5. Do not confuse 401/403, protocol errors or empty tools with a missing route

For remote MCP clients the official WordPress guide describes Application Passwords over HTTPS. Their availability depends on secure site configuration and host/security-plugin policy. Use a separate, revocable Application Password per client and an account with only the capabilities the integration actually needs. The right solution to 401/403 is to examine the authorized client flow and role, not to disable access checks.

The official MCP Adapter 0.7.x line includes specific Streamable HTTP protocol and session handling. A real MCP request can fail from an unsupported client protocol version or omitted session headers without being a WordPress rewrite problem. The protocol troubleshooting reference explains missing Mcp-Session-Id and request-lifecycle errors. Do not manually invent protocol headers against production to “make it work”; test with a client that supports the server’s documented protocol version.

If the client connects and shows the adapter’s discovery tools but no usable abilities, that is not a 404. WordPress Abilities are not automatically exposed as privileged agent tools. Review the registration, MCP exposure metadata and permission callbacks of the intended ability. For local inspection see our Abilities API checks. A successful connection should never imply that administrative actions can safely be executed without approval.

6. Audit the local evidence without pretending it repairs MCP

Once a functioning wp-admin is available, ModelGain Agent Readiness Audit provides an independent read-only diagnostic. Its Actionability rules include detecting the MCP Adapter and its version, and checking registered MCP REST route evidence where WordPress can expose it locally. It also distinguishes observations from unknown outcomes. This is useful after an integration update or when documenting an incident for a site owner.

Limit: a local audit cannot prove the public endpoint survives a WAF, a specific client’s HTTPS Application Password reaches the server, a remote MCP handshake succeeds or an ability executes with correct permissions. It cannot alter routing, install adapter dependencies, enable a default MCP server or repair the 404. To test those facts, use a controlled client session and the appropriate trusted logs. If the plugin cannot establish enough evidence, treat an Unknown as an investigation cue, not as a failure or a pass.

When the site’s general REST routing is the underlying fault, the right companion is our generic REST 404 diagnosis. For ongoing WordPress plugin/system integration repair, see ModelGain WordPress Development only after the responsible layer is identified.

Production verification checklist

• Routing: the WordPress REST index works through the expected pretty or documented query-route form; the official default MCP path and supported methods match what the client uses.
• Registration: the intended default or custom server route exists in the correct running WordPress installation; its owning plugin and other bundled integrations are version-identified.
• Authorization: a real approved MCP client connects over HTTPS using a dedicated revocable credential; unauthorized requests remain unauthorized.
• Function: non-destructive discovery works for the intended profile, with no accidental exposure of private or write-capable abilities. Do not use production mutations as a smoke test.
• Regression: the original client stops reporting the 404, unrelated REST routes/front-end workflows remain healthy, and private proxy/WordPress logs contain no new unexpected failures.
• Recovery record: log the previous and new plugin versions, route/HTTP method, response type, confirmed root cause, approved change and reversible rollback path.

Frequently asked questions

Why does /wp-json/ work but /wp-json/mcp/mcp-adapter-default-server return 404?

A working REST index proves the main REST router is reachable, not that this exact path and tested HTTP method are registered. Verify the adapter plugin’s release, route registration, default-server filter and the client’s HTTP method. If a browser’s GET gets 404, do not infer that the correct MCP POST method fails without checking.

Will reinstalling or resaving permalinks always fix rest_no_route?

No. They do not fix a default MCP server deliberately disabled by another plugin. Verify the error source first; changing production rewrite settings without knowing the layer can introduce new regressions.

Is the MCP Adapter the same as WebMCP?

No. WordPress MCP Adapter exposes WordPress Abilities to compatible MCP clients over HTTP/STDIO. Browser-side WebMCP support for Contact Form 7 is a separate integration model. Installing one does not automatically configure the other.

Can I make the MCP endpoint public to fix an authorization error?

No. A 401/403 normally requires checking supported authentication and capabilities, not removing them. Default ability discovery and the permission to perform write/privileged actions are separate questions.

Does the ModelGain audit plugin fix MCP route registration?

No. It is a local evidence and risk-audit tool. It can help distinguish missing components or routes from unverified external behavior, but it does not change the adapter’s configuration, register missing servers or run an authenticated client connection.

The resolution criterion is a working authorized client journey—not HTTP 200 alone. Record whether the original failure was a wrong URL/method, host rewrite, incomplete adapter installation, disabled default-server filter, or an authentication/protocol mismatch. That evidence also determines whether you need a hosting change, upstream plugin update or no WordPress change at all.