Troubleshooting | AI Connector docs

Things go wrong. This page covers the most common AI Connector problems and how to fix them.

If your problem isn’t here, open an issue on GitHub — including reproduction steps and any error messages from the WP debug log makes us much faster to help.

Connection issues

”Failed to connect” when adding an OAuth connection

Symptoms: the OAuth authorize page either won’t load, fails with a redirect error, or returns an “invalid_client” error.

Common causes and fixes:

HTTPS is required in production OAuth flows. Check your site URL — if it starts with http:// (no S), enable HTTPS first. Local dev environments allowed HTTP, production isn’t.
Site URL mismatch. Go to Settings → General and check that WordPress Address (URL) and Site Address (URL) match what you’re actually using. A trailing slash difference can break OAuth redirects.
Rewrite rules. If permalinks are set to “Plain”, switch to a structured format (e.g. “Post name”) and re-save. AI Connector’s REST endpoints rely on rewrite rules.
Caching. Aggressive page caching can return a stale OAuth response. Bypass cache for the /wp-json/oxai/* and /wp-login.php paths during connection.
Security plugin blocking REST. Plugins like Wordfence, iThemes Security, or All-in-One Security sometimes block wp-json paths by default. Whitelist /wp-json/oxai/*.

”Authorization expired” on an existing connection

OAuth refresh tokens are valid until you revoke. If a connection still says “expired” after refreshing, it usually means:

The connection was revoked elsewhere (check the audit log for a connection_revoked entry)
The plugin was deactivated and reactivated, which clears OAuth state
The site URL changed since the connection was created

Fix: revoke the broken connection and re-authorize from scratch. Old tokens won’t come back.

Tools not appearing in your AI client

Claude Desktop doesn’t show “Axtolab AI Connector” in MCP servers

Check Claude Desktop’s MCP server settings. The connection must be listed there. If it isn’t, the OAuth handoff didn’t complete — try the Copy connection details button on the AI Connector page and paste them in manually.
Restart Claude Desktop. MCP servers are loaded at app startup; new connections sometimes need a restart to register.
Check Claude Desktop logs. On macOS, they’re in ~/Library/Logs/Claude/. Look for entries with mcp or axtolab.

Tools list is empty inside Claude

Connection succeeded but no tools show up:

Capability set was too narrow. Check the connection’s permissions at AI Connector → Connections → [your connection]. If only the read group is enabled (e.g. the read_only preset), you’ll only see read tools — no wp_create_draft, wp_publish_content, etc.
Plugin needs to be active. Deactivating the plugin disconnects all clients silently — they may still appear connected in Claude until restart but return empty tool lists.
Rate limit hit during initial handshake. Check AI Connector → Settings → Rate Limits → Recent activity.

Tool execution errors

”rest_forbidden” or “Sorry, you are not allowed…”

The connection’s OAuth scope doesn’t permit the action. Two fixes:

Revoke the connection and re-authorize with broader scope. Note that scope can only widen by re-authorizing — there’s no in-place upgrade.
Check WP user capabilities. OAuth scope is bounded by the WP user that authorized the connection. If you authorized as an editor, you can’t grant manage_options even if you select that scope.

”Rate limit exceeded”

Too many requests per minute from the same IP or connection.

Default limit: 60 req/min per IP. Adjust under AI Connector → Settings → Rate Limits.
Per-connection limit: Each OAuth connection has its own bucket. If multiple agents share one connection, they share the bucket — split into separate connections.
Burst patterns: Some agents make many tool calls in quick succession (e.g. listing 100 posts then editing each). The burst window setting controls how forgiving the rate limit is to bursts.

”Yoast tools not registered”

Yoast SEO tools only appear when the Yoast plugin is active. If you’ve installed Yoast but tools are missing:

Make sure Yoast is activated, not just installed
Re-authorize the connection — tools registered after the connection was created don’t retroactively appear
Check that your plan tier of Yoast (free vs Premium) supports the API endpoints AI Connector uses; the free plan is sufficient for all the tools we expose

Performance issues

Site is slow when an agent is connected

Audit log table is large. The free core’s audit log keeps everything indefinitely. For high-traffic sites, prune old entries: AI Connector → Settings → Audit Log → Prune entries older than [N days].
Database indexes missing. A few WP setups (mostly older installs) need a manual index rebuild: run wp db optimize via WP-CLI.
Hosting limits. Some shared hosts throttle aggressive REST API usage. Check with your host’s logs if you suspect this.

OAuth flow takes 10+ seconds

The OAuth flow does several round trips on first connection — initial discovery, authorize, token exchange. 10 seconds is at the upper edge of normal but not broken.

If it’s consistently 30+ seconds:

DNS issues. Check your site’s external DNS resolution time
Slow PHP startup. PHP-FPM with cold processes adds latency on first request
Caching layer not bypassing OAuth paths. See the OAuth connection issues section above

Plugin update issues

Plugin updated but Connections page is broken

After a plugin update, the connections page fails to load:

Deactivate and reactivate the plugin. This re-runs the activation hook which migrates the database schema if needed.
Check for PHP errors in WP debug log. Enable WP_DEBUG_LOG in wp-config.php, look at wp-content/debug.log.
Clear object cache. If you use Redis or Memcached: wp cache flush.

Existing OAuth tokens stopped working after update

Tokens are preserved across normal updates. If they break:

Major version bump? Major versions sometimes require token re-issue (we’ll announce this in the release notes if so).
Plugin reinstall instead of update? Reinstalling clears OAuth state. Use Update, not delete-and-reinstall.

Where to get help

If nothing here fixes your issue:

GitHub Issues — github.com/Axtolab/wordpress-mcp-server/issues. Include WP version, plugin version, AI client + version, what you tried, and any error messages from the debug log.
WP.org support forum — slower but visible to other users hitting the same thing.
Email support — support@axtolab.com for paid add-on customers.

When opening an issue, the most useful data points are:

Plugin version and WP version
AI client and version
The exact error message (screenshot or copied text)
Steps to reproduce
WP debug log output if WP_DEBUG is enabled