Troubleshooting Easy MCP AI Connection Issues

If your AI assistant will not connect to your site, work through the three steps below. Most connection failures are not in the plugin itself. They come from the hosting, CDN, security, or caching layer sitting in front of WordPress, and these steps identify which one it is in a couple of minutes.

If you receive HTTP 405 while saving settings or connecting, see Fix HTTP 405 Errors.

The plugin has all of this built in. You do not need to run any commands.

In this article

• Step 1: Run the Diagnostics Inside WordPress
  • How to Read the Results
• Step 2: Test the Connection from the Internet
• The Usual Causes
• Step 3: Send Support the Details
• Security

Step 1: Run the Diagnostics Inside WordPress

1. Go to Easy MCP AI > Dashboard in your WordPress admin.
2. Find the Diagnostics card and press Re-run.

Easy MCP AI keeps the last results for slower checks and shows when they were measured in a Checked [time ago] line. After you change your site address or permalinks, affected results may be marked out of date. Connection checks can also rerun automatically in the background while the Dashboard or connection flow is open. Press Re-run when you need a fresh result from every diagnostic group; automatic connection checks do not run the complete suite.

How to Read the Results

Result	Meaning
Pass	Checked and healthy.
Warn	A sign worth ruling out, not proof of a fault.
Fail	A directly observed fault. Start here.
Skipped / Unknown	The check could not run. This proves nothing either way. Do not read it as a pass or as a failure.

Anything marked BLOCKING is what to fix first.

Some built-in checks run from inside WordPress, but checks that contact your public MCP endpoint can still be intercepted by a host, CDN, WAF, or bot filter before Easy MCP AI receives them.

Step 2: Test the Connection from the Internet

On the same Diagnostics card, press Test from the internet.

This opens the external checker with your site address already filled in. It probes your site the way an AI assistant's servers would, from outside. It reports whether your site is reachable, whether the plugin answers, whether OAuth discovery works, and whether anything in front of WordPress is intercepting the request.

Step 1 and Step 2 answer different questions, and you need both. Step 1 tells you whether WordPress and the plugin are healthy. Step 2 tells you whether anything outside can actually reach them. A site can pass every check in Step 1 and still be unreachable from the internet.

The Usual Causes

Most connection problems come down to one of these:

• The Authorization header is stripped before it reaches PHP. This is the most common cause of "it worked yesterday and now my token is rejected". An orange Authorization-header warning does not automatically mean the connection is broken. On some FastCGI setups, this diagnostic can be inconclusive even when authentication works, so you can ignore the warning if the checks in the Authentication group pass and your AI connector works.

  If an Authentication check fails, refresh WordPress's rewrite rules and run the diagnostic again:

  1. Go to Settings > Permalinks and click Save Changes without changing the permalink structure.
  2. Return to Easy MCP AI > Dashboard, find Diagnostics, and press Re-run.

  If authentication passes and your connector works after the check runs, no further action is needed. If authentication or the connector still fails, follow the server troubleshooting below. If the failed check offers Add the rewrite rule to .htaccess, use it and let the checks run again. If .htaccess is not writable, choose Copy the rule and paste it into your site's .htaccess file above the WordPress block. On Apache with FastCGI, ask your host to enable CGIPassAuth On; if the server uses mod_fcgid, it may need FcgidPassHeader Authorization instead. On nginx, the server configuration needs the equivalent fastcgi_param. Ask your host to confirm that the relevant rule applies to the active document root, that its configuration allows the required .htaccess override, and that security rules are not stripping the header. Share the diagnostic details with them.

• A REST security plugin blocks anonymous requests before Easy MCP AI can authenticate them. Easy MCP AI can bypass anonymous 401 blockers only on Easy MCP AI REST routes. It does not override explicit 403 policy decisions. If the connection is still blocked, re-run Diagnostics and use the conflict details to identify the blocking plugin.

• A host, CDN, or firewall bot-challenge or rate limit answers before WordPress does. An AI assistant is not a browser, so anything that requires solving a JavaScript or CAPTCHA challenge will block it permanently. If you see HTTP 403, 500, or 202 together with a CAPTCHA, robot challenge, or host-branded response page, the edge layer answered before WordPress. HTTP 202 by itself is not proof. An HTTP 429 or “Rate limit exceeded” response can also come from host-level rate limiting, such as Imunify360 WebShield, before the request reaches WordPress.

  If A9 reports Something in front of WordPress is refusing the AI assistant with HTTP 403 Forbidden, the request was refused before Easy MCP AI could respond. An unauthenticated probe that reaches the MCP endpoint should receive 401 Unauthorized, Easy MCP AI's authentication challenge. Test from the internet and A9 can use different request profiles, so a passing internet test confirms only that its own request reached the endpoint; it does not rule out a block against the request A9 tested.

  To investigate, re-run Diagnostics and note the endpoint and any request identity shown in the failure details. Check the matching host, CDN, or WAF event, or ask your host to identify the blocking rule and request. Ask them to add a narrow exception for that request identity on /wp-json/easy-mcp-ai/v1/mcp. Do not disable site-wide security or Easy MCP AI authentication. For Cloudflare-specific checks and targeted rules, see Troubleshoot Cloudflare Blocking Easy MCP AI Connections.

  After the rule change, re-run Diagnostics. If the unauthenticated A9 probe returns 401 Unauthorized instead of 403, it has reached Easy MCP AI and the endpoint is still requiring authentication.

  For other bot-challenge or rate-limit blocks, ask your host, CDN, or security provider to add a narrow exception for non-browser requests to /wp-json/easy-mcp-ai/ and /.well-known/ for the rule generating the response, instead of disabling security globally. After they adjust this, run Test from the internet again, confirm the response is from WordPress (not a host challenge page), and reconnect your AI client.

• The root /.well-known/ addresses are handled by the host before WordPress sees them. Easy MCP AI also publishes OAuth discovery below the MCP endpoint, which compatible clients such as ChatGPT and Codex can use automatically. Reconnect your client and run Test from the internet before changing server files. If this fallback also fails or your client does not support it, use an API token when available. A token does not bypass an edge block on the MCP endpoint itself. If you need to keep using OAuth, ask your host to route the root discovery paths to WordPress or install the plugin-generated discovery documents in your site's public-root .well-known/ directory, then run Test from the internet again.

• A security or caching plugin interferes with the sign-in redirect, so the approval screen never appears or approving appears to do nothing. A maintenance or coming-soon mode can also replace the OAuth approval screen, which blocks sign-in even when other checks look fine. Temporarily make the WordPress front-end approval screen publicly accessible, run Test from the internet once more, reconnect your AI client, and confirm the normal WordPress approval screen appears.

• The diagnostics show Failed Every API token can see tools - "Claude" (user 1) sees no tools - the WordPress user this token belongs to does not have permission for any of them. This usually means the token is assigned to an unresolved user (shown as unknown) or a user that lacks permission for every selected tool. Open the token in Creating and Managing API Tokens, reassign it to an active WordPress account with enough capability for the tools you need, enable those tools, and save. Then refresh tools in your AI client or start a new conversation so it discovers the updated tool list instead of using the old cached empty one. For the refresh steps in each AI client, see Enabled Tools Not Showing in Your AI Client.

Two more quick checks worth ruling out:

• The endpoint returns 404. Open Easy MCP AI > Dashboard and press Re-run on the Diagnostics card. Follow the failed Plain-permalink routing check. On Apache or LiteSpeed, choose Keep Plain and route sign-in through .htaccess to add the OAuth discovery and sign-in rules without changing your permalink structure; Diagnostics reruns the connection checks automatically. If PHP cannot write .htaccess, choose Copy the rules and add the block shown in Diagnostics to your site's .htaccess file or ask your host to add it. nginx, Caddy, and IIS do not use .htaccess; follow the server-specific guidance in Diagnostics or choose a non-Plain permalink structure.

• Another MCP plugin is active on the same site. AI clients may get confused when multiple OAuth endpoints are detected. Disable other MCP plugins and reconnect.

Step 3: Send Support the Details

If it is still not working, the support team is happy to look at it directly. On the same Diagnostics card:

1. Press Copy System Info & Diagnostic and save the result.
2. Press Test from the internet and copy that result too.
3. Reach out through the contact page and paste both results into your message.

Please include:

• What you were trying to do.
• What happened instead, including the exact error your AI client shows. "It says it cannot connect" is much harder to act on than the real wording.
• When it started, and anything that changed just before: a plugin update, a host migration, a new security or caching plugin, a CDN being switched on.
• The diagnostics from Step 1.
• The external test result from Step 2.
• Your site address, if you are willing to share it. It is the single thing that lets the team reproduce the problem instead of guessing.

The report never includes passwords, tokens, or anything identifying your users. Those are removed automatically and appear as "[details withheld]". Leave them as they are.

Investigate it yourself with AI

The Diagnostics card also has a Copy AI Prompt button. It produces a ready-made prompt you can paste into any AI assistant along with your diagnostics, if you would rather dig in yourself first.

Security

If you identify a potential security vulnerability in this plugin, please disclose it responsibly. Follow the protocols on the Themeisle Security Page.