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.
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
- Go to Easy MCP AI > Dashboard in your WordPress admin.
- Find the Diagnostics card and press Re-run checks.
Pressing the button matters. Some of the most useful checks are slower, so they do not run on a normal page load. Until you press it, you will see a line saying a number of slower checks were not run. Press it and wait a few seconds.
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.
These checks run from inside your site, so nothing at your CDN or firewall can distort 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". The diagnostics test this directly.
- A host, CDN, or firewall bot-challenge 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. This usually has to be relaxed by your host, and your site will look perfectly healthy in your own browser.
- The
/.well-known/addresses are blocked or handled by the host before WordPress sees them, which breaks sign-in. - A security or caching plugin interferes with the sign-in redirect, so the approval screen never appears or approving appears to do nothing.
- A token was saved with no tools selected. An empty tool list means no access, not full access. See Creating and Managing API Tokens.
Two more quick checks worth ruling out:
- The endpoint returns 404. Go to Settings > Permalinks and click Save Changes to flush the rewrite rules. Pretty permalinks must be enabled for the endpoint to register.
- 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:
- Press Copy System Info & Diagnostic and save the result.
- Press Test from the internet and copy that result too.
- 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.