Connect an AI Agent

Grandranker runs an MCP server, so an AI agent can research keywords, write and publish articles, and read your rankings and AI visibility for you. This page has the copy-paste setup for each client and the full tool list.

• MCP endpoint: https://app.grandranker.com/mcp/grandranker
• Auth: Authorization: Bearer YOUR_API_TOKEN. Create a token at Settings → API Tokens (https://app.grandranker.com/settings/api-tokens). Steps: REST API & Tokens.
• Plain-text docs for agents: every docs page is also Markdown at its URL + .md (for example /docs/agents.md). The index is /llms.txt, the full text is /llms-full.txt.

Claude Code

Run this in your terminal, with your token in place of YOUR_API_TOKEN:

Copyclaude mcp add --transport http grandranker https://app.grandranker.com/mcp/grandranker --header "Authorization: Bearer YOUR_API_TOKEN"

Then run /mcp inside Claude Code to check that grandranker is connected.

Cursor

Add this to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for every project):

Copy{
  "mcpServers": {
    "grandranker": {
      "url": "https://app.grandranker.com/mcp/grandranker",
      "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
    }
  }
}

Open Cursor Settings → MCP and check that grandranker shows a green dot.

VS Code

Add this to .vscode/mcp.json in your workspace. VS Code asks for the token the first time and stores it securely:

Copy{
  "inputs": [
    { "type": "promptString", "id": "grandranker-token", "description": "Grandranker API token", "password": true }
  ],
  "servers": {
    "grandranker": {
      "type": "http",
      "url": "https://app.grandranker.com/mcp/grandranker",
      "headers": { "Authorization": "Bearer ${input:grandranker-token}" }
    }
  }
}

Open Copilot Chat in Agent mode and pick the Grandranker tools from the tools menu.

ChatGPT (developer mode)

1. In ChatGPT, open Settings → Apps & Connectors → Advanced settings and turn on Developer mode.
2. Go back to Apps & Connectors and click Create.
3. Name it Grandranker and paste https://app.grandranker.com/mcp/grandranker as the MCP server URL.
4. Pick OAuth as the authentication and click Create.
5. Sign in with your Grandranker account when asked.
6. In a new chat, pick Developer mode from the + menu and turn on the Grandranker connector.

Available tools

Each tool needs the matching token scope and only reaches websites in your own workspace. Most tools take a domain_id, so start with list_domains.

Tool	What it does
list_domains	List your websites and their IDs
get_domain	Get one website with its brand profile and article settings
list_keywords	List keywords with volume, difficulty, intent and status
get_keyword	Get one keyword with its latest rank and status
add_keyword	Add a keyword
research_keywords	Start AI keyword research (runs in the background)
list_articles	List articles with status and published state
get_article	Get one article with full content, scores and status
get_article_social_posts	Read the social captions already generated for an article
score_article	Get SEO, quality and readability scores
generate_article	Generate an article from a keyword (runs in the background)
regenerate_article	Rewrite an article using the current settings (runs in the background)
edit_article	Edit an article's fields
publish_article	Publish a completed article to your connected platform
unpublish_article	Unpublish an article back to draft
get_ai_overview_visibility	AI-search visibility across Google AI Overviews, AI Mode, ChatGPT, Perplexity, Claude and Gemini
list_ai_overview_queries	List monitored AI-search queries with their latest status
get_rank_overview	Rank-tracking summary and position distribution
list_tracked_keywords	Tracked keywords with current position and change
get_keyword_rank_history	Position history for one tracked keyword
get_settings	Read the business data, audience and writing instructions
update_business	Update business data
update_audience	Update target audience, ICP, pain points and competitors
update_article_settings	Update writing instructions and article settings (overwrites, doesn't append)
list_api_endpoints	List every REST endpoint the agent can call
api_request	Call any REST endpoint that has no dedicated tool

generate_article, regenerate_article and research_keywords count against your plan limits and return right away. The agent then checks get_article or list_keywords until the result is ready.

A first prompt to try

List my Grandranker websites, then show the 10 keywords with the lowest difficulty for the first one and generate an article for the best match.