What is the Lumos MCP server?

It is a hosted Model Context Protocol (MCP) server that lets AI assistants like Claude, ChatGPT, Codex, and Cursor read your Lumos AI search visibility data — visibility scores, competitors, citations, sentiment, and GEO recommendations — in plain language.

Is the Lumos MCP server read-only and secure?

Almost entirely. It reads your data and can never create, delete, or edit content or settings. The single exception: your agent may mark a recommendation completed or ignored (reversible), so finished work stops being re-recommended. Access is OAuth-scoped to companies you are a member of, and you can revoke any connection under Settings → MCP Connections.

Which AI clients can connect to Lumos over MCP?

Claude (Desktop and claude.ai), ChatGPT, Claude Code, Codex, Cursor, VS Code, and any other MCP-compatible client.

How do I connect Lumos to Claude or ChatGPT?

Add https://api.trylumos.ai/mcp as a custom (remote) MCP connector in your client, then approve access when the browser opens. Full setup steps are on this page.

Lumos MCP Server

Connect Lumos to your AI assistant and ask about your AI search visibility, competitors, sources, and recommendations in plain language. Secure, OAuth-scoped access.

Server URL

https://api.trylumos.ai/mcp

Supported clients

Claude (Desktop & claude.ai) — custom connector
ChatGPT — custom connector
Claude Code & Codex — CLI (see below)
Cursor, VS Code, and other MCP-compatible clients

Setup

Add https://api.trylumos.ai/mcp as a remote MCP connector in your client. You'll be sent to Lumos to sign in and approve access. For example, in a client that uses a JSON config:

{
  "mcpServers": {
    "lumos": {
      "url": "https://api.trylumos.ai/mcp"
    }
  }
}

On first connect, a browser window opens to authorize the connection. You can revoke access any time under Settings → Connections.

Claude Desktop

In Claude Desktop, open Settings → Connectors and click Add custom connector. Enter:

Name: Lumos
Remote MCP server URL: https://api.trylumos.ai/mcp

Click Add, then Connect — a browser opens for you to sign in to Lumos and approve access. The Lumos tools then appear in the tools menu of any chat. Custom connectors require a paid Claude plan (Pro, Max, Team, or Enterprise).

On an older version without Connectors, add Lumos to your claude_desktop_config.json instead (Settings → Developer → Edit config):

{
  "mcpServers": {
    "lumos": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.trylumos.ai/mcp"]
    }
  }
}

Restart Claude Desktop; a browser opens once to authorize.

Claude Code

Add Lumos from your terminal:

claude mcp add --transport http --scope user lumos https://api.trylumos.ai/mcp

Then run /mcp inside Claude Code and choose to authenticate — a browser opens for you to sign in and approve access. Verify it connected with claude mcp list.

Codex

Add Lumos from your terminal:

codex mcp add lumos --url https://api.trylumos.ai/mcp

Or add it to ~/.codex/config.toml:

[mcp_servers.lumos]
url = "https://api.trylumos.ai/mcp"

Codex opens a browser to sign in and approve access. List your servers with codex mcp list.

Available tools

Once connected, your assistant can call these tools on your behalf. Most take a company slug from list_companies. You don't call them directly — just ask in plain language and the assistant picks the right ones.

Discovery

list_companies — List the companies (brands) you can access — names + slugs. Call this first to get the slug other tools need.e.g. “Which brands can you see in my Lumos account?”

Visibility & ranking

get_visibility — Headline AI-visibility stats: visibility score, mention rate, sentiment counts, citation share, and average rank.e.g. “What's my AI search visibility score right now?”
get_visibility_history — Visibility score over time (default last 30 days), optionally by category or score type.e.g. “How has my visibility trended over the last 90 days?”
get_position_history — Average ranking position over time (default last 30 days).
get_ranking_metrics — Position / ranking metrics, optionally filtered by category.
get_rankings_by_topic — Rankings broken down by prompt category / topic.e.g. “Which topics am I ranking best and worst on?”

Competitors

get_leaderboard — Competitor leaderboard / share of voice.e.g. “Who are my top competitors by share of voice?”
list_competitors — List the competitors tracked for a company.
get_competitor_mentions — Recent AI-response mentions for a specific competitor.e.g. “Show recent AI mentions of my biggest competitor.”
get_brand_detection — Brands discovered in AI responses.

Sentiment

get_sentiment_analysis — Sentiment analysis with theme breakdown, optionally by category.e.g. “What themes drive positive vs negative sentiment about my brand?”
get_sentiment_history — Sentiment metrics over time (default last 30 days).

Sources & citations

get_sources — Top cited sources / domains in AI responses.e.g. “What sources do AI engines cite most about my brand?”
get_source_history — Citation history for a specific source URL.

Recommendations

get_recommendations — Latest GEO recommendations.e.g. “Summarize my latest GEO recommendations and what to do first.”
list_recommendation_runs — Past recommendation runs (not just the latest).e.g. “How have my recommendations changed over the last few runs?”
get_recommendation_run — All recommendations from one specific run.
list_recommendation_content — Content drafts created from a recommendation.e.g. “Which recommendations already have a draft written?”
get_recommendation_content — The full generated draft (paste-ready article/body) created from a recommendation.
get_implementation_guide — A complete implementation package for one recommendation: plan, content draft with structured data, brand guidelines, target queries, GEO checklist, and verification steps — everything your coding agent needs to build it.e.g. “Implement my top Lumos recommendation on my site.”
mark_recommendation_status — Mark a recommendation completed (or ignored) when the work ships, with an optional note on what was published where — the only write action, reversible.e.g. “Mark that recommendation as done — published at /es/metodologia.”

SEO & audit

get_seo — SEO snapshot (keywords, competitors).
get_audit — Latest technical SEO audit.

Prompts & evaluations

list_prompts — Tracked prompts with their metrics.
get_evaluations — Evaluation results, optionally scoped to a single run.

Try asking

“How is my AI search visibility trending this month?”
“Who are my top competitors by share of voice?”
“What sources do AI engines cite about my brand?”
“Summarize my latest GEO recommendations.”

FAQ

What is the Lumos MCP server?: It is a hosted Model Context Protocol (MCP) server that lets AI assistants like Claude, ChatGPT, Codex, and Cursor read your Lumos AI search visibility data — visibility scores, competitors, citations, sentiment, and GEO recommendations — in plain language.
Is the Lumos MCP server read-only and secure?: Almost entirely. It reads your data and can never create, delete, or edit content or settings. The single exception: your agent may mark a recommendation completed or ignored (reversible), so finished work stops being re-recommended. Access is OAuth-scoped to companies you are a member of, and you can revoke any connection under Settings → MCP Connections.
Which AI clients can connect to Lumos over MCP?: Claude (Desktop and claude.ai), ChatGPT, Claude Code, Codex, Cursor, VS Code, and any other MCP-compatible client.
How do I connect Lumos to Claude or ChatGPT?: Add https://api.trylumos.ai/mcp as a custom (remote) MCP connector in your client, then approve access when the browser opens. Full setup steps are on this page.

The MCP is read-only for all your data — the single exception is marking a recommendation completed or ignored, so your agent can close the loop. It can never create, delete, or edit content or settings.