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/mcpThen 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.
claude mcp add --transport http rankxai https://app.rankxai.com/api/mcp \ --header "Authorization: Bearer rxai_your_token_here"Create the token first, in RankX AI's MCP settings, on the API tokens tab. Creating a token is owner-only.
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.
- Claude Code calls
https://app.rankxai.com/api/mcpwithout a token. RankX AI answers401with a header that points to its OAuth metadata. - 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. - Your browser opens on RankX AI's approval screen. Sign in, check what the connection can do, and select Approve connection.
- 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 see | What to do |
|---|---|
| The browser does not open | Run 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 listThen 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-auditcurl -o .claude/skills/rankxai-visibility-audit/SKILL.md \ https://rankxai.com/agent-skills/rankxai-visibility-audit.mdThe full list, with what each does, is on the Agent Skills page.
How do I remove the connection?
claude mcp remove rankxaiThat 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
- Authentication and scopes for scopes and client-scoped credentials.
- Examples for prompts that work.
- Troubleshooting if a tool you expected is absent.
- Connect Claude on the web and desktop to add RankX AI as a custom connector.
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