MCP troubleshooting
Fix RankX AI MCP problems: a missing tool points to scope, a connector that fails to attach usually has the wrong sign-in, and each refusal names its fix.
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 usually means the wrong sign-in method for that client.
Find your symptom below; each section starts with the most likely cause.
Why is a tool missing?
Usually because the credential does not carry the tool's scope. A tool whose scope your credential lacks 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 |
Audits, checks, research, articles and page-optimisation proposals: the ten spend tools | spend |
Anything beginning wp_ for content, media or SEO | publish |
Any tool beginning shopify_, including the reads | 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 has no downtime.
On an OAuth connection, a missing tool means the connection was approved before that capability existed. RankX AI tells the assistant which capabilities are missing when it connects. Remove the old connector, then add it again, and the new connection gets the full set.
One tool has its own switch. wp_advanced_request stays hidden until an
administrator turns the escape hatch on for that specific connection, so it can
be missing from a credential that has site_admin.
In ChatGPT, a tool added to RankX AI after you connected may need a refresh of the server in ChatGPT's Plugins page, because ChatGPT keeps a snapshot of a custom server's tools.
Why do no tools appear at all?
The connection is not attached. Check, in order:
- The endpoint is
https://app.rankxai.com/api/mcp, with nothing after it. - The sign-in method matches the client. Claude and ChatGPT sign in with OAuth; the editors and scripts send a token. See the client table.
- In Claude, the connector is on for this chat. Select +, then Connectors, and switch RankX AI on.
- The token is still valid. Tokens expire after the 30, 90 or 365 days chosen at creation, and RankX AI's MCP settings show each token's expiry and last use.
- The account owner approved it. Only an account owner can approve an OAuth connection or create a token.
- The account is a RankX AI web account. The MCP server is part of the web app; a store using the Shopify app works inside Shopify instead.
Why does sign-in say "Connection request rejected"?
RankX AI does not recognise the app's registration. The message says either that the requesting app is not registered, or that it supplied a redirect address it did not register.
Both come from an invented or copied client ID. Remove the connector, add it again, and leave the client ID and secret empty: in Claude, choose Register automatically. RankX AI then registers the app itself, and no access was granted by the failed attempt.
Why does sign-in say only the account owner can approve?
Because only an owner can approve. The approval screen tells anyone else to ask the owner to connect the app, and grants nothing. Ask the owner to add the connection from their own login, or to create a token for you.
Why does Claude Desktop say 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 ignored, and the app reports only that some
servers failed to load. The snippet that looks right is an editor's config, a
different format for a different mechanism.
Add RankX AI as a custom connector with OAuth, which is the supported path,
or use the local bridge on
the Claude Desktop page. On Windows the
bridge needs two details, and both fail silently: wrap the command in cmd /c,
and put the credential in an environment variable, because the bridge splits
the header argument on its first space.
Why did the connection work, then stop?
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 theft rather than a bug. Reconnect, and if it recurs, the client is not saving the new refresh token.
An OAuth connection also has a 180-day lifetime, after which you approve it again.
If you use a token: check the MCP settings page. A token stops at its expiry date, when it is revoked, and 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.
Why was a call 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 to change on your side. 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.
Why did a call return nothing?
Check whether you used a dispatch-and-poll capability. These tools return at once and finish the work in the background:
| Started with | Poll with |
|---|---|
start_site_audit | get_site_audit_status, then get_site_audit_issues |
write_article | get_article_run, then get_content_item |
generate_article | get_content_item |
get_keyword_trends | get_keyword_trends_status |
publish_content_item | get_publication_status |
propose_page_optimisation | get_page_optimisation |
run_shopping_check | get_shopping_prompt_detail |
create_content_brief | get_content_brief |
Reading the dispatch response as the answer is the most common integration mistake on this surface.
Also check whether the empty result is honest. A tool that has nothing to
report says so, and get_site_timeline lists what it cannot see on every
response: an empty timeline means "no record", not "nothing happened".
Why did a number come back as null?
Because nothing was measured. null means unknown, never zero, on every metric
field, and the tools say so in their own responses.
Do not let an assistant show it as 0%. That tells you that you are invisible when the truth is that nothing was measured. See null is not zero.
Why did a Google tool refuse 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 the
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.
Why was a WordPress write refused?
The refusal names the case. The three common ones:
The page is built with a builder that stores content outside the page body. Edit it in the builder itself. Every body write from a tool is refused rather than half-applied, which keeps the page's layout intact.
The SEO fields are not writable on this site. That depends 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.
Why does the page look unchanged after a write?
Almost always a page cache. RankX AI verifies a write by reading the object back, which confirms the database changed and catches a plugin that reports success while saving nothing. A cache in front of the site can still serve the old version, and RankX AI adds a note saying so to every successful content and SEO write.
A write reported as unverified is different: RankX AI could not confirm it and says so rather than claiming success. Check the object in wp-admin.
Why am I being rate limited?
Two windows, both per account and shared across every credential on it:
| Window | Limit | Covers |
|---|---|---|
| Requests | 600 per hour | Every request to the MCP endpoint |
| Writes | 120 per hour | Every tool call whose scope is not read |
A write uses one of each, so the write window is the one you reach first when publishing. Both fail closed: an unreadable limiter denies rather than allows.
Back off rather than retrying at once. The two usual causes are polling a dispatch-and-poll pair too often, which uses up the 600, and a bulk publishing loop, which uses up the 120.
Where to go next
- Authentication and scopes for scopes, revocation and limits.
- The tool reference for what each tool requires.
- Examples for what a correct answer looks like.
Questions
What should I send support when the MCP connection fails?
Three things: which client you use, which credential type, and the exact message you saw. Every RankX AI refusal names its own cause and remedy, so quoting it usually saves a round trip.
Is polling a background job charged?
No. The status tools for audits, articles, keyword trends and publishing are free reads, so poll at a sensible interval without worrying about credits.
Can a Shopify app store connect over MCP?
The MCP connection is part of the RankX AI web app for WooCommerce and other websites. On Shopify, RankX AI works inside your Shopify admin through the Shopify app.
Last updated