Skip to content
Docs

Connect Claude Code

Connect Claude Code to the RankX AI MCP server with one claude mcp add command, then sign in with OAuth through /mcp or send a personal access token header.

Claude Code connects to RankX AI with one command, and it supports both credential types. Use OAuth when a person is at the keyboard, and a personal access token when the connection has to work unattended or with fewer permissions.

claude mcp add --transport http rankxai https://app.rankxai.com/api/mcp

Then run /mcp inside Claude Code and choose RankX AI to sign in, or run claude mcp login rankxai in your shell. A browser opens for you to sign in and approve. An account owner has to approve the connection.

How does Claude Code authenticate with the RankX AI MCP server?

The Claude Code CLI authenticates with OAuth and PKCE, and finds everything it needs from the RankX AI MCP server itself. You only approve the connection in your browser.

  1. Claude Code calls https://app.rankxai.com/api/mcp without a token. RankX AI answers 401 with a header that points to its OAuth metadata.
  2. Claude Code reads that metadata and registers itself through dynamic client registration, with a redirect address on your own machine (localhost), so there is no client ID or secret to enter.
  3. Your browser opens on RankX AI's approval screen. Sign in, check what the connection can do, and select Approve connection.
  4. Claude Code exchanges the authorisation code for an access token, which lasts an hour, and a refresh token it uses to renew it in the background.

You sign in again only when the connection is disconnected or reaches its 180-day limit.

What if Claude Code authentication fails?

The error message usually names the cause:

Error you seeWhat to do
The browser does not openRun claude mcp login rankxai in your shell, or choose RankX AI in /mcp again
"Only the account owner can approve"Sign in as the RankX AI account owner, or ask the owner for a token
"Connection request rejected"Remove the server and add it again without --client-id, so Claude Code registers itself
401 with "Invalid API token."The token is missing or mistyped, or the header lacks the word Bearer
401 with "This API token has expired." or "has been revoked."Create a new token on the API tokens tab and update the header

Should I use OAuth or a token?

Use OAuth when a person will be at the keyboard. It is one command, there is no secret in your shell history, and disconnecting it is one click in RankX AI.

Use a token when any of these is true:

  • The connection has to work unattended, with nobody to sign in at a browser.
  • You want a read-only credential, so an assistant can report but never write or spend. OAuth grants the full capability set in one decision; a token picks its scopes.
  • You want a token that expires on a date you choose: 30 days, 90 days or a year.

Both credentials can be limited to one client's websites. A token chooses that when you create it, and the OAuth approval screen offers Which websites when your account has more than one client.

How do I check the connection works?

claude mcp list

Then ask for something:

Using RankX AI, list my websites and show me the AI visibility for the first one over the last 30 days.

The assistant should call list_projects first. Every other tool takes a website id it returns, so that call is the entry point rather than a formality.

Which scope should the connection use?

claude mcp add uses the local scope by default: the connection is stored for you, in the current project only. Add --scope user to make it available in every project.

To share it with everyone working in one repository, use --scope project, which writes the repository's .mcp.json. Commit that file without the token in it, using an environment variable reference instead:

{
"mcpServers": {
"rankxai": {
"type": "http",
"url": "https://app.rankxai.com/api/mcp",
"headers": {
"Authorization": "Bearer ${RANKXAI_TOKEN}"
}
}
}
}

Anything that puts a rxai_ token into a committed file is a leaked credential. If it happens, revoke it in RankX AI's MCP settings and issue a new one; rotation has no downtime.

How do I use the RankX AI Agent Skills?

RankX AI publishes written workflows as Agent Skills. Copy the ones you want into your project's skills directory and Claude Code will use them:

mkdir -p .claude/skills/rankxai-visibility-audit
curl -o .claude/skills/rankxai-visibility-audit/SKILL.md \
https://rankxai.com/agent-skills/rankxai-visibility-audit.md

The full list, with what each does, is on the Agent Skills page.

How do I remove the connection?

claude mcp remove rankxai

That removes the connection and its stored sign-in from your machine. To end access everywhere, also disconnect the app on the Connected apps tab of RankX AI's MCP settings if you used OAuth, or revoke the token on the API tokens tab if you used one.

Where to go next

Questions

I already added RankX AI on claude.ai. Do I need to add it again?

No, if you log in to Claude Code with the same claude.ai account. Connectors you added on claude.ai appear in Claude Code automatically. A server you add with claude mcp add takes precedence over a connector with the same address.

Where does Claude Code store the RankX AI connection?

With the default local scope, in your user configuration file for the current project only. Add --scope user to use it in every project, or --scope project to write a shared .mcp.json file.

Does claude mcp remove revoke access?

It deletes the connection and its stored sign-in from your machine. To end access on the RankX AI side, disconnect the app or revoke the token in RankX AI's MCP settings as well.

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.