WordPress MCP Not Connecting? Troubleshooting Claude + Your WordPress Site

MCP looks magical when it works. Claude reads your WordPress posts, runs an audit, suggests fixes, applies them with one approval — and you're done in ten minutes. When it doesn't work, the failure modes are quiet: Claude says "no tools available," or the OAuth flow loops forever, or write tools throw 401s with no obvious cause.

This is the troubleshooting guide I wish I'd had when I was building Connect My Site to AI. Most of these symptoms are universal across MCP servers (the troubleshooting steps apply whether you're running my plugin, the Automattic adapter, Royal MCP, or WP MCP Ultimate); a few are specific to my plugin and I'll flag those. If you're brand new to the protocol, read MCP servers explained first.

Quick Diagnostic Checklist

Before going through the symptoms below, run this 60-second checklist. It eliminates 80% of issues:

• Plugin is active. Site Health → Plugins. If your MCP plugin is deactivated, no tools work.
• HTTPS is required. MCP requires HTTPS — local http:// URLs won't work with hosted Claude. Use a tunnel (ngrok, Cloudflare Tunnel) for local dev.
• REST API reachable. Visit https://yoursite.com/wp-json/ in a browser. If you see JSON, the REST API is alive. If you see 404 or 500, your MCP endpoint can't work either.
• No security plugin blocking REST. Wordfence, iThemes Security, and Solid Security can block the REST API or specific routes. Whitelist your MCP endpoint.
• AI client is restarted. Claude Desktop in particular caches tool lists. Quit fully (not just close window) and reopen after any config change.

Symptom: Claude Says "No Tools Available"

You connected the server, the OAuth flow succeeded, but Claude shows zero tools. This is the most common failure and it has three usual causes:

• Tool list cached. Quit Claude Desktop fully and relaunch. The MCP tool list is fetched on connection; if you connected before the plugin was active, you got an empty list and Claude is showing the cached version.
• Wrong server URL. Double-check the URL in your client config. For Connect My Site to AI it's https://yoursite.com/wp-json/cmsta/v1/mcp. Other plugins use different paths. A trailing slash, a typo in the prefix, or copying the WordPress.com URL when you're self-hosted will all silently fail to "no tools."
• OAuth scope is too narrow. If you authorized with only the read scope and the plugin's tool list is gated on a wider scope, the server may report no tools rather than 403'ing each one. Re-run the auth flow and approve all requested scopes.

Symptom: Connection Times Out

The client tries to reach the MCP endpoint and never gets a response. Almost always this is a network or hosting issue, not an MCP issue:

• Hosting blocks unusual request patterns. Some shared hosts (Bluehost, GoDaddy) flag MCP's long-lived JSON-RPC connections as suspicious and silently drop them. Check the host's firewall logs.
• WAF is filtering the request. Cloudflare, Sucuri, and SiteGround's WAF can block requests with certain JSON shapes or content-type headers. Whitelist the MCP route.
• PHP execution limit is too low. Some MCP tools (find_orphan_content, list_posts on a 5,000-post site) need 60+ seconds. If max_execution_time is 30, the request times out mid-tool. Bump it to 120s in php.ini or .user.ini.
• HTTP not HTTPS. MCP over HTTP often gets blocked by the AI client's networking layer. Force HTTPS at the WordPress level (wp-config.php: define('FORCE_SSL_ADMIN', true);) and confirm there's no mixed-content warning.

Symptom: Authentication Loop

You click "approve" in the OAuth consent screen, the browser redirects, and you end up back at the consent screen. Forever.

• PKCE state mismatch. The client sent one code_verifier and the server is comparing against a different one — usually because cookies were blocked, the auth flow was opened in incognito, or the redirect went to a different domain (www vs non-www, http vs https). Make sure your WordPress siteurl and home match exactly what the AI client is using.
• Redirect URI not whitelisted. Some MCP plugins maintain a list of allowed redirect URIs. If the AI client sends a redirect URI the plugin doesn't recognize, the auth completes but the token exchange silently fails. Check the plugin settings for an allowed-redirects field.
• Cookies disabled or partitioned. Browser strict-tracking settings can partition cookies in a way that breaks the OAuth state cookie. Try a different browser or disable strict tracking for the auth flow.
• Token expired between authorize and exchange. If clock drift is bad on the server, the auth code may already be expired by the time it arrives back. Make sure NTP is running on your server.

Symptom: Tools Fail With 401 or 403

Read tools work, but write tools (update_post, create_post, bulk_update_meta) return 401 Unauthorized or 403 Forbidden. This is almost always license + scope:

• Pro license missing or expired. Connect My Site to AI gates all 23 write tools behind an active license. Check Settings → Connect My Site to AI → License. The license server checks every 12 hours; if your card expired, the plugin will fall back to read-only after the next check.
• Write scope not granted. Even with an active license, the OAuth token has to include the write scope. If you authorized with only read, write tools 403. Re-run the auth flow and approve write scope explicitly.
• WordPress user lacks the capability. Subscriber and contributor accounts can't edit posts. The user account behind the OAuth flow needs edit_posts, edit_others_posts, or higher depending on the operation. Connect with an Editor or Administrator account.
• Bulk cap exceeded. Connect My Site to AI caps bulk operations at 50 items per call. Asking Claude to "update meta on 200 posts" will 403 at item 51. Have Claude batch in groups of 50.

Symptom: Claude Can't Find Specific Posts

You know the post exists but search_content returns zero results. Three usual culprits:

• Post status filter. By default, search tools query published posts only. Drafts, scheduled, and pending posts are excluded unless you ask explicitly. Tell Claude "include drafts" or pass status: 'any'.
• Custom post types. The default search hits post and page. WooCommerce products, portfolio items, and custom post types need to be passed explicitly. Ask Claude "search products" rather than "search posts."
• Post is private or password-protected. Private posts are returned only when the OAuth user has read access. Confirm the underlying WordPress user can see the post in the admin.

Symptom: SEO Press / Yoast / Rank Math Plugin Conflicts

You're searching for "seo press connection fail with claude" or seeing weird MCP behavior alongside an SEO plugin. Most SEO plugins add fields to posts (focus keyword, meta description, schema settings) and some intercept the REST API to enforce permissions on those fields:

• Yoast SEO blocks REST writes for non-Editor roles. If Claude is connecting as an author/contributor, Yoast may block updates to its own meta fields. Connect as an Editor or Administrator.
• Rank Math caches its own meta separately. Updating _yoast_wpseo_metadesc or rank_math_description via MCP may not refresh until the SEO plugin's cache is cleared. Most plugins have a "Clear Transients" or "Update Cache" button.
• SEOPress requires its own field names. If Claude tries to update generic meta_description, SEOPress ignores it because it stores under _seopress_titles_desc. Ask Claude to write to the SEOPress field names directly, or use a plugin like Connect My Site to AI's update_seo_elements tool which auto-detects the active SEO plugin.
• Multiple SEO plugins active simultaneously. If both Yoast and Rank Math are active (don't do this), they fight over the same hooks and MCP writes go to whichever plugin loaded last. Pick one SEO plugin.

Symptom: License Says "Active" But Pro Tools Still Locked

Specific to Connect My Site to AI, but the pattern applies to any licensed plugin. Two scenarios:

• License activated on the wrong site. Each license covers one site. If you activated on staging and now you're hitting production, production has no license. Deactivate on staging first, then activate on prod.
• Plugin update transient is stale. WordPress caches plugin update info for 12 hours. If you just renewed, it may take up to 12h for the plugin to register that the license is active again. Trigger a manual check by visiting Plugins → check for updates.

Where to Get Help

If you've worked through the checklist and you're still stuck, the fastest path to a fix is sharing two things: the exact error message (copy-paste, not paraphrase) and the MCP server URL you're using. With those, most issues are diagnosable in one round-trip.

For Connect My Site to AI users, support is included in the Pro license — the contact form on the plugin page goes straight to me. For the Automattic adapter or WordPress.com MCP, the WordPress.org support forums and Automattic's MCP docs are your best paths.

Once you're past the connection issues, the complete MCP setup guide and the tasks you can automate with WordPress + AI are the natural next reads. If you're still picking which MCP server to install, the WordPress MCP server comparison covers the trade-offs.