Fix MCP connection problems

Most connection problems come down to one of four things: agent access is off, the token is wrong, the request never reaches WordPress with its header, or the token isn't allowed to use a tool. This page lists every message RankKit SEO returns, grouped by where you see it.

Start with a quick test

Run the test from the cURL tab on RankKit SEO → AI Agents in a terminal, with your endpoint and token:

curl -s https://example.com/wp-json/speedrank/v1/mcp \
  -H "Authorization: Bearer sr_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"site_overview","arguments":{}}}'

• A JSON reply with your site's name means the server and token work, and the problem is in the client's configuration.
• An error message tells you which row below applies.
• An HTML page, a login page or a firewall message means something in front of WordPress (a security plugin, host firewall or maintenance mode) is blocking /wp-json/ requests.

Then check RankKit SEO → AI Agents: the token's Last used column and the Activity card show whether the call reached RankKit SEO.

Connection and sign-in errors

Message	Cause	Fix
"AI agent access is turned off. Enable it in RankKit SEO → AI Agents."	Allow AI agents to connect is off (HTTP 403).	Turn it on in RankKit SEO → AI Agents.
"Invalid or expired RankKit SEO agent token."	The token is mistyped or incomplete, was revoked, has expired, or its WordPress user was deleted (HTTP 401).	Create a new token and update your client. Copy the whole token, starting with sr_.
"Authentication required: send Authorization: Bearer ."	No token reached WordPress (HTTP 401). Either the client didn't send the header, or the web server stripped the Authorization header before WordPress saw it.	Check the header in your client's configuration. If it is correct, send the token in an X-RankKit-Token: sr_… header instead, which RankKit SEO also accepts.
"Application Password access is disabled. Use a RankKit SEO agent token."	The client signs in with an Application Password and Also accept WordPress Application Passwords is off (HTTP 401).	Use an agent token, or turn the toggle back on.
"This user cannot use SEO tools."	The Application Password belongs to a user who can't edit posts (HTTP 403).	Use an account with at least edit access, or an agent token.
"This MCP server does not offer an SSE stream. Use POST."	The client opened the endpoint with GET (HTTP 405). RankKit SEO uses Streamable HTTP with JSON responses and no SSE stream.	Use a client or setting that supports Streamable HTTP. A browser visit to the endpoint also shows this; it is harmless.

claude.ai and ChatGPT sign-in errors

Message or symptom	Cause	Fix
The app can't connect, or /.well-known/ URLs return 404	Pretty permalinks are off, or OAuth or agent access is off.	Choose Post name in Settings → Permalinks, and turn on Allow AI agents to connect and Allow sign-in from claude.ai, ChatGPT and other web connectors (OAuth).
The app can't reach the site	The site is local, private or not on HTTPS.	claude.ai and ChatGPT need a public HTTPS site. Use a desktop client with a token for local sites.
"OAuth connections are turned off for this site."	OAuth or agent access is off (HTTP 403).	Turn both on in RankKit SEO → AI Agents.
"Too many registrations from this address. Try again later."	More than 20 connection attempts from one address within an hour (HTTP 429).	Wait an hour and try again.
"Provide at least one https (or localhost) redirect_uri."	The app registered without a valid return address.	Start the connection again from the app. If it persists, the app doesn't support this sign-in.
"This connection request is not valid" with "The app is not registered with this site or its return address does not match."	The app's registration is missing or expired, or the return address changed.	Start the connection again from the app.
"This connection request is not valid" with "The app must use the authorization code flow with PKCE (S256)."	The app doesn't use the required sign-in method.	Start again from the app. Apps without PKCE support can't connect.
"Ask an administrator": "Only site administrators can connect AI assistants to RankKit SEO."	You signed in with a non-admin account.	Sign in as an administrator.
"The site owner declined the request."	Cancel was clicked on the consent screen.	Start again and click Allow access.
"The authorization code is invalid, expired or already used."	The sign-in took too long or was repeated.	Start the connection again.
"PKCE verification failed."	The app's sign-in data didn't match.	Start the connection again.
"The refresh token is invalid or revoked."	The connection was revoked, expired after 90 days, or a refresh token was reused (which revokes the whole connection).	Reconnect from the app.
"Use authorization_code or refresh_token." or "Parameters must be strings."	The client sent an unsupported or malformed token request.	Reconnect; if it repeats, the client isn't compatible.

Tool and permission errors

Message	Cause	Fix
"This token does not have write access to "content". The site owner can change scopes in RankKit SEO → AI Agents." (or read access, or another area)	The token's permissions don't include that area at that level.	Create a token with the right permissions and revoke the old one. See Agent tokens.
"Your WordPress user cannot do this."	The token's WordPress user lacks the capability the tool needs, for example a non-admin calling run_audit.	Use a token created by a user with that permission, or adjust the role manager.
"Agent, AI and tracking settings can only be changed by a person in wp-admin."	The agent tried to change a locked setting (agent, AI, analytics, AI visibility or tracking settings, or those modules).	Change it yourself in wp-admin.
"Unknown tool: …"	The tool doesn't exist on this site: it needs RankKit SEO Pro, a Google connection or WooCommerce, or the name is wrong.	Check the MCP tool reference.
"… is part of RankKit SEO Pro. Start a 14-day free trial or upgrade to use it."	A Pro tool was called while the Pro license isn't active.	Activate or renew your license, or start a free trial.
"Missing required argument: …"	A required input was left out.	Ask the agent to call the tool again with that argument.
"Nothing to change: pass at least one field."	A settings tool was called with no fields.	Ask the agent to pass the field it wants to change.
"Only applied changes can be reverted."	revert_change was called on a pending, rejected or already reverted change.	Use withdraw_change for your own pending changes; approve or reject others in the Change Log.
"This field changed again after this edit. Revert the newer change first, or force it."	A newer change touched the same field.	Revert the newer change first, or force the revert in RankKit SEO → Change Log.

A write that returns status pending isn't an error: with approval mode on, the agent is told "Queued for approval. A site admin must approve it in RankKit SEO → Change Log before it goes live." A site-wide change returns pending_approval and waits for an administrator whether approval mode is on or off. See Approval mode, dry runs and undo.

AI tool errors

Tools that write with RankKit SEO's AI (names starting with ai_, and some others) use your own AI provider key.

Message	Fix
"Add an AI provider key in RankKit SEO → Settings → AI."	Add a key in RankKit SEO → Settings → AI provider. See Add your AI provider key.
"Connect an AI provider in WordPress (Settings → Connectors) to use WordPress AI."	You chose WordPress AI as the provider; connect a provider in WordPress first.
"AI features are turned off."	Turn on the AI assistant module on the Dashboard.
"AI is paused in RankKit SEO settings."	Turn off Pause all AI in RankKit SEO → Settings → AI provider.
"Daily AI request limit reached. Raise it in settings or try tomorrow."	Raise the Daily request limit in RankKit SEO → Settings → AI provider, or wait until tomorrow.

Protocol errors

These come from the MCP protocol layer and usually mean a client bug or a hand-written request.

Message	Cause
"Parse error"	The request body isn't valid JSON.
"Batch requests are not supported"	The client sent several JSON-RPC calls in one array. Send them one at a time.
"Method not found: …"	The client called an MCP method RankKit SEO doesn't support.
"Unknown prompt: …"	The workflow doesn't exist or isn't available on this site (it needs Pro or Google). See Ready-made workflows.
"Resource not found: …"	The resource doesn't exist, or the token lacks the access it needs.

Missing tools or workflows

If the client connects but shows fewer tools than you expect:

• Token permissions hide tools the token can't use.
• The token's WordPress user must have the capability each tool needs.
• RankKit SEO Pro adds 27 tools, Google adds 3 free and 5 Pro tools while Search Console and GA4 are connected, and 2 Pro tools need WooCommerce. See MCP tool reference.
• Some clients only read the tool list when they start. Restart the client after changing a token or connecting Google.

FAQ

My token worked yesterday and fails today. Why?

It has probably expired. Check the Expires column in Agent tokens. Expired tokens show Expired and are removed a day later.

The cURL test works but my client doesn't. What next?

The server and token are fine, so check the client's configuration: the endpoint URL, the header format and, for Claude Desktop, that Node.js is installed. Restart the client after editing its configuration.

Does RankKit SEO log failed calls?

Calls that reach a tool are logged in the Activity card with Error and the message. Requests rejected before that (such as an invalid token or agent access turned off) are not logged there.