WordPress MCP troubleshooting, fixed fast.

• Open HandyMCP › Connection and click Check again under Connection check. It tests the server, sign-in and your host.
• Make sure the site uses HTTPS and Settings › Server › MCP server is on.
• Security plugins and firewalls (Wordfence, Cloudflare WAF, Sucuri, your host) can block the REST API. Allow /wp-json/handymcp/ and the /oauth/ URLs.

Turn on Settings › Server › OAuth sign-in and Automatic app registration. Both are needed by Claude and ChatGPT connectors. You still approve every app.

• Go to Settings › Permalinks and click Save changes without changing anything.
• Plain permalinks (?p=123) are not supported. Pick any other structure.

• The sign-in expired, or the token was paused, revoked or expired. Resume it, or disconnect and connect again.
• Some hosts strip the Authorization header. Ask your host to pass it through, or use OAuth instead of a token.

• A firewall blocked the request. Allow /wp-json/handymcp/ and the /oauth/ URLs.
• The user who approved the app has a role that is not in Settings › Access › Allowed roles, or lacks permission for that task. Connect with an administrator.

Claude and ChatGPT only connect to sites on HTTPS.

• Install an SSL certificate. Most hosts offer a free one (Let's Encrypt) in their control panel.
• Then set both addresses in Settings › General to https://.
• Local test sites on http:// work with Cursor, VS Code and Claude Code through an access token.

• In your security plugin or firewall (Wordfence, Sucuri, Cloudflare WAF, your host), allow /wp-json/handymcp/ and the /oauth/ URLs.
• In your cache plugin or CDN, exclude /wp-json/handymcp/ from caching. The MCP endpoint must never be cached.
• Click Check again on the Connection screen to confirm.

This is only a note, not a problem. Claude and ChatGPT sign in with OAuth, and Cursor, VS Code and Claude Code use HandyMCP access tokens. Neither needs Application Passwords.

• If an app can only sign in with an Application Password, click Allow them for MCP only on the Connection screen. They then work for HandyMCP requests and stay off everywhere else.
• Or turn the option off in your security plugin, for example Wordfence › Login Security › Settings › Disable WordPress application passwords.

Open Settings › General and make WordPress Address and Site Address the same, with the same www or no www and both on https://. Apps connect to the Site Address.

A persistent object cache (Redis or Memcached) is fine, but if sign-ins fail at random, flush it from your cache plugin or host panel and try again. HandyMCP does not need an object cache.

• Check the token is pasted with Bearer in front, and that it has not expired.
• Restart the app or reload its MCP servers. Most apps load tools when they start.

That prompt comes from your AI app, not from HandyMCP. HandyMCP still applies your scopes, abilities and confirmations, so allowing tools in the app is safe.

• Claude: Settings › Connectors, click your WordPress connector and set its tools to Always allow.
• Claude Code: choose Yes, and don't ask again, or add "mcp__wordpress" to permissions.allow in .claude/settings.json.
• ChatGPT: tick Remember on the confirmation.
• Cursor: Settings › Chat, turn on Auto-run.
• VS Code: choose Always allow on the prompt, or turn on chat.tools.autoApprove.
• Windsurf: turn on Auto execution for MCP tools.
• Gemini CLI: add "trust": true to the server in ~/.gemini/settings.json.

• Turn off Settings › Server › Read-only mode.
• Check the scopes you approved (or the token's scopes) include Edit content or what the task needs.
• Check the tool is on under Abilities.
• Check the app is not paused on the Connection screen.

• The tool group may be off on the Abilities screen, or it may be a Pro or Agency feature. See Free, Pro and Agency.
• With Tool list: Compact, the AI finds tools on demand. Ask it to "look for a tool that can do this".
• Start a new chat after updating HandyMCP or adding keys.

Add the role under Settings › Access › Allowed roles and save. The AI can never do more than that role allows.

Each connection may make a set number of reads and changes per minute. For big bulk jobs, raise Changes per minute under Settings › Limits, or ask the AI to work in smaller batches.

After too many wrong sign-ins (10 by default) an address is blocked for 15 minutes. Wait, then sign in again. You can change the number under Settings › Limits.

• Ask for the work in smaller steps, for example one page or 20 products at a time.
• Raise max_execution_time to at least 60 seconds with your host.

Set Settings › Server › Tool list to Compact. It sends core tools first and looks up the rest only when needed.

• Clear your cache plugin or host cache (LiteSpeed, WP Rocket, Cloudflare), or ask the AI to purge the cache.
• Check if the AI made a draft. Redesigns are saved as drafts so the live page stays safe.

• Open Elementor › Tools and click Regenerate files and data.
• Still wrong? Open Undo history and undo the last change for that page.

The free plugin keeps the last 20 changes. Pro keeps everything for the days set in Settings › Limits › Keep undo history. Raise it to keep changes longer.

Undo it from Undo history, then repeat the request with the exact page URL.

• Without keys, photos come from Openverse only. Add a free key under Settings › Photos.
• For Unsplash use the Access Key, not the Secret Key, and paste it without spaces.
• Ask by name: "search Unsplash for a bright office photo". Start a new chat after saving keys.

Video search needs a Pexels key (Unsplash has no videos). Save the key, update HandyMCP to the latest version and start a new chat.

Your host may block outgoing downloads or limit upload size. Ask them to allow requests to images.pexels.com, videos.pexels.com and images.unsplash.com, and to allow uploads of at least 64 MB.

• Check Automatic updates is on and the schedule shows "Next run" under the Schedule title.
• The schedule uses WP-Cron, which runs when someone visits the site. On quiet sites, ask your host to run WP-Cron from a real server cron.
• Click Save and run now to test it.

HandyMCP found an error on the home page, login, REST API or admin-ajax after the update and restored the old version. The email report names the plugin. Tick it under Never update until its developer fixes the issue.

• Check the address under Email the report to and the frequency setting.
• Make sure your site can send email. An SMTP plugin such as WP Mail SMTP helps.

• Open the private link you saved, signed in as an administrator.
• Or ask your AI app: "turn white label off".
• Or delete the handymcp_hide_from_admins option with your host's database tool.
• It also shows itself after 30 days without MCP activity.

• The client site needs HandyMCP installed and active, and an access token with Site admin.
• Paste the full address with https://.
• A firewall on the client site may block the hub. Allow /wp-json/handymcp/.

Create a new access token on that site and add the site again on the hub. Old tokens stop working on their expiry date.

The client sites hub is part of the Agency plan. Upgrade from your account; you keep the same key.

• Check the key has no spaces, and the plan has a free site slot. Remove old sites in your account.
• Your server must reach handymcp.com. Ask your host if outgoing requests are blocked.

Install HandyMCP Pro (the trial email has the download link), then paste the key under HandyMCP › License. The free plugin alone cannot use a key.

Check spam and promotions. You can get your keys again from your account, or contact support.