MCP troubleshooting
Why a tool is missing, why a connector will not attach, what each refusal means, and the two client traps that cost the most time.
Two symptoms cover most of what goes wrong. A tool is missing almost always means the credential does not carry that tool's scope, not that anything is broken. The connector will not attach at all is usually the wrong connection method for that client.
Work down the list by symptom.
"A tool is missing"
This is the expected behaviour, not a fault. A tool whose scope your credential does not carry is omitted from the tool list entirely, and calling it anyway returns "unknown tool", indistinguishable from a tool that does not exist. Capability is not discoverable, deliberately.
| What you cannot see | The scope you are missing |
|---|---|
| Creating prompts or tasks, saving keywords, pausing a prompt | write |
| The six tools that spend credits | spend |
Anything beginning wp_ for content, media or SEO | publish |
| WooCommerce products | commerce |
| Site configuration and the advanced request | site_admin |
Scopes are fixed when a credential is issued and cannot be widened. Issue a new token with the scopes you need, update the client, and revoke the old one. Rotation is zero downtime.
Two special cases. An OAuth connection is granted the full set, so if OAuth is
your path and a tool is missing, the cause is not scope. And
wp_advanced_request is hidden until an administrator switches the escape hatch
on for that specific connection, so it can be missing on a credential that has
site_admin.
"No tools appear at all"
The connection is not attached. In order:
- Check the endpoint is
https://app.rankxai.com/api/mcp, with no trailing path. - Check the method matches the client. Claude Desktop, Claude Web and ChatGPT need OAuth; the editors and scripts need a token. See the client table.
- Check the token has not been revoked on RankX AI's MCP settings page, which shows each credential's last use.
- Check who approved it. Only an account owner can approve an OAuth connection or issue a token.
- Check the plan. MCP access is on every plan, so this is only a cause if an account-level override has switched it off.
"Claude Desktop says some servers failed to load"
claude_desktop_config.json cannot take an HTTP entry with headers. That
file starts local programs, so an entry describing a remote HTTP server with an
Authorization header is silently ignored and the app reports only that some
servers failed to load. Nothing names the cause, and the snippet that looks
like it should work is the one from an editor's config, which is a different
format for a different mechanism.
Use the Connectors panel with OAuth, which is the supported path, or the local bridge form on the Claude Desktop page. If you use the bridge on Windows, two details are load-bearing and both fail silently: wrap the command so the shell can start it, and put the credential in an environment variable rather than inline, because the bridge splits the header argument on its first space.
"The connection worked, then stopped"
If you use OAuth: check whether the connection was revoked. RankX AI revokes a whole connection when it detects a replayed authorisation code or a reused refresh token, because either is evidence of credential theft rather than of a bug. A client that fails to persist a rotated refresh token will be disconnected rather than degraded. Reconnect, and if it recurs, the client is not storing the new value.
If you use a token: check the MCP settings page. A token can be revoked directly, and it is also revoked when the person who created it is removed from the account.
Either way: check the subscription. A lapsed subscription stops MCP access, and the refusal says so rather than looking like a broken connection.
"A call was refused for credits"
Four refusals, four different remedies, and only one is fixed by adding credits:
| Refusal | Remedy |
|---|---|
| Not enough credits | Add credits, or reduce recurring spend |
| Subscription not active | Reactivate the subscription |
| Client budget exceeded | The agency raises that client's allocation |
| Action not priced | Nothing you can do. It is a fault on our side and the message says so |
The third is agency-only, and it catches people out because the agency wallet can be full while one client is stopped: a per-client budget is a ceiling on the shared wallet rather than a separate pot. See per-client credit budgets.
"It returned nothing, and I think it failed"
Check whether you used a dispatch-and-poll capability. Three of them return an id immediately and finish the work minutes later:
| Started with | Poll with |
|---|---|
start_site_audit | get_site_audit_status, then get_site_audit_issues |
generate_article | get_content_item |
get_keyword_trends | get_keyword_trends_status |
Reading the dispatch response as the answer is the most common integration mistake on this surface. Polling is free.
Also check whether the empty result is honest. A tool that genuinely has nothing
to report says so, and several of them report their own blind spots alongside:
get_site_timeline lists what it cannot see on every response, and an empty
timeline means "no record", not "nothing happened".
"A number came back as null"
That is a real answer. null means unknown, never zero, on every metric field in
the surface, and the tools say so in their own responses.
Do not let an assistant render it as 0%. That tells you that you are invisible when the truth is that nothing was measured. See null is not zero.
"A Google tool refused instead of returning figures"
By design. A Google connection is in one of four states and only one yields
numbers. Call get_google_integration_status, which is free, and it names which
state and what to do: connect it, reconnect it, wait for the first sync, or
select a property.
RankX AI refuses rather than reporting zero, because "no traffic" and "we cannot see your traffic" are different facts and only one of them is about your website.
"A WordPress write was refused"
The refusal names the case. The three common ones:
The page is built with a builder that stores content outside the page body. No tool can edit it and every attempt is refused rather than half-applied. That is a guarantee, not a limitation to work around.
The SEO fields are not writable on this site. Whether they are depends entirely on the site's SEO plugin. The refusal carries the remedy, including the registration snippet with your site's own field names where one would fix it.
A bulk call arrived without its dry run. A live bulk update is refused unless it carries the batch id the dry run returned for exactly that list of ids. Change the list and you need a new dry run.
"A write succeeded but the page looks unchanged"
Almost always a page cache. RankX AI verifies a write by re-reading the object, which confirms the database changed, and that is the only signal that catches a plugin returning success while persisting nothing. A cache in front of the site can still serve the old version, and RankX AI appends a note saying so to every successful content and SEO write.
If the write was reported as unverified, that is different and more serious: RankX AI could not confirm it and is telling you so rather than claiming success. Check the object in wp-admin.
"I am being rate limited"
Two windows, both per account and shared across every credential on it:
| Window | Limit | Covers |
|---|---|---|
| Calls | 600 per hour | Every tool call |
| Writes | 120 per hour | Every call whose scope is not read |
A write consumes one of each, so the write window is the one you hit first when publishing. Both fail closed: an unreadable limiter denies rather than allows.
Back off rather than retrying immediately. Two usual causes: polling a dispatch-and-poll pair too tightly, which burns the 600, and a bulk publishing loop, which burns the 120.
Still stuck
Three things make a support conversation short: which client you are using, which credential type, and the exact message you saw. Every refusal on this surface is written to name its own cause and its remedy, so quoting it usually skips a round trip.
Where to go next
- Authentication for scopes, revocation and limits.
- The tool reference for what each tool requires.
- Examples for what a correct answer looks like.
Examples
Twelve worked recipes for RankX AI over MCP. The prompt to paste, the tool sequence it produces, and what to watch for in the answer.
Running an agency
How the RankX AI agency track is organised. Client Workspaces, roles, the seven visibility permissions, per-client budgets, white label and the client portal.