Skip to content
Docs

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 seeThe scope you are missing
Creating prompts or tasks, saving keywords, pausing a promptwrite
Audits, checks, research, articles and page-optimisation proposals: the ten spend toolsspend
Anything beginning wp_ for content, media or SEOpublish
Any tool beginning shopify_, including the readspublish
WooCommerce productscommerce
Site configuration and the advanced requestsite_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:

  1. The endpoint is https://app.rankxai.com/api/mcp, with nothing after it.
  2. 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.
  3. In Claude, the connector is on for this chat. Select +, then Connectors, and switch RankX AI on.
  4. 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.
  5. The account owner approved it. Only an account owner can approve an OAuth connection or create a token.
  6. 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:

RefusalRemedy
Not enough creditsAdd credits, or reduce recurring spend
Subscription not activeReactivate the subscription
Client budget exceededThe agency raises that client's allocation
Action not pricedNothing 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 withPoll with
start_site_auditget_site_audit_status, then get_site_audit_issues
write_articleget_article_run, then get_content_item
generate_articleget_content_item
get_keyword_trendsget_keyword_trends_status
publish_content_itemget_publication_status
propose_page_optimisationget_page_optimisation
run_shopping_checkget_shopping_prompt_detail
create_content_briefget_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:

WindowLimitCovers
Requests600 per hourEvery request to the MCP endpoint
Writes120 per hourEvery 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

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

Cookie settings

Choose which cookies we can use. You can change this at any time from “Cookie settings” in the footer.

Essential

Security, bot protection and remembering your choice. The site needs them to run, and they do not identify you. Always on.

Google Analytics cookies that tell us which pages are read and which links are followed, so we can improve them. Off until you switch it on.

Tells advertisers when their advert led to your visit. Includes the Meta (Facebook) pixel and the LinkedIn Insight Tag, which set cookies on this domain (LinkedIn also on linkedin.com) and can be told if you later start a trial.

More in the cookie policy and the privacy policy.