Cituna MCP: the AI visibility MCP server

Cituna MCP is the official MCP server for Cituna, the AI visibility tool: your AI agent reads how seven AI engines answer, mention and cite your brand every day, next to your Google Search Console data, and acts on it with 31 tools.

The seven engines are ChatGPT, Perplexity, Gemini, Claude, Grok, Google AI Overviews and Google AI Mode, and every tracked prompt is asked on all of them daily. Connect the server to Claude, ChatGPT, Cursor, VS Code or any other MCP client and you can ask which buyer questions you are losing, what each engine actually answered, which pages it read, and what to fix first, then have the agent fix it.

It is hosted, speaks Streamable HTTP, and signs you in with OAuth in your browser. One URL, nothing to install:

https://mcp.cituna.com/mcp

Running it yourself instead, for scripts, CI or a client without OAuth? The same server is on npm. It takes a personal API key and needs Node 20 or later:

npx -y cituna-mcp

Product page and full docs: cituna.com/mcp.

Contents

• What your agent can do
• Try asking
• Quick start: claude.ai, Claude Desktop, Claude Code, ChatGPT, Cursor, VS Code, Windsurf, Codex CLI, Gemini CLI, any other client
• Tools
• Plans and access
• Built-in workflows
• What a session looks like
• Connecting Google Search Console
• Authentication and security
• Self-hosting the remote server
• Troubleshooting
• FAQ
• Links

What your agent can do

Most AI visibility tools hand you a dashboard and leave the thinking to you. Cituna puts the measurements where you already reason: ask your agent why an engine never mentions you, and it pulls the answer receipts, checks them against what Google already sends you, and queues the page that fixes it, without you opening a tab.

• Read the daily tracking grid. Which of your tracked prompts each engine cited you for today, at what position, and your current visibility score (get_visibility).
• Pull the receipts. What an engine actually answered for one prompt, the brands it named and the URLs it cited (get_engine_answers).
• Find where the answers come from. The third-party pages the engines cite for your prompts, how often, which rivals each one names, and whether you are on the page, read from the page itself rather than guessed (list_citation_sources).
• Spot new rivals. Brands the engines name in answers to your own buyer questions, and vendor names people search before reaching you, that you are not tracking yet (competitor_discovery).
• Join AI answers with Google. Search Console totals, any Search Analytics query, and six ready-made analyses: queries just off page one, pages seen and not clicked, demand by intent, pages never shown, your own pages competing, and searches worded like AI prompts (gsc_*).
• Work the fix queue. Every gap from your latest audit with its impact, effort and the concrete fix, and its status as you go (list_gaps, set_gap_status).
• Plan and ship content. Keywords with real demand and nothing written for them, the AutoSEO queue and every article it wrote, then queue, edit, refresh or skip from the chat (list_keywords, queue_article, update_article, enrich_article).
• Change what is measured. Add, disable or rewrite the buyer questions the seven engines are asked every day, with a before-and-after diff (set_prompts).
• Run a fresh scan when you have shipped a fix and want to look now (run_scan).
• Keep an outreach list. Mark a cited source as planned, pitched, placed or declined, so the list survives between sessions (set_outreach_status).

Try asking

Once connected, ask in plain English. The server tells your agent which tools and workflow answer which kind of question, so you do not have to name them.

Visibility and receipts

• "How is acme.com doing in AI search today? Which prompts and engines cite us?"
• "What did Perplexity answer for best CRM for dentists, and who did it cite instead of us?"
• "What changed in my AI visibility this week, and which engines dropped us?"
• "Why don't AI engines mention us? Use the not-cited diagnosis."

Sources and competitors

• "Which sites does each engine read for our prompts that don't mention us yet? Rank them as a pitch list."
• "Which of our own pages do the engines already cite?"
• "Who comes up instead of us, and which rivals aren't we tracking?"
• "Mark the G2 category page as pitched." (Pro)

Search Console, joined up

• "Which queries are just off page one, and which page ranks for each?"
• "Which pages get impressions and no clicks, and why?"
• "Where do Google impressions exist but AI never cites us? That is my AEO target list."
• "Do two of our pages compete for the same query?"
• "How many of our searches look like AI prompts?"

Fixes and content

• "List the open gaps for acme.com, ranked by the Search Console impressions each one touches."
• "Which keywords have demand and no page behind them? Queue the top three." (Pro)
• "Which AutoSEO articles are due a refresh? Refresh them." (Pro)
• "Add the three questions we lost this week to our tracked prompts, and disable the ones nobody searches." (Pro)
• "Run a fresh scan for acme.com and summarise the top 3 gaps." (Pro, uses one scan)

Quick start

You need a Cituna account on Starter or a higher plan, with at least one tracked brand. The 3-day free trial is app-only: MCP access starts when your plan does. A brand-new workspace has nothing to read yet, so add your brand in the app first (cituna.com).

There are two ways to connect, and both expose exactly the same tools:

claude.ai (web and mobile)

1. In Claude, open Customize → Connectors, click Add, then Add custom connector.

2. Name it Cituna and paste the URL:

   https://mcp.cituna.com/mcp
   

3. Claude sends you to Cituna to sign in, then shows a consent screen. Leave Also allow changes ticked to let Claude run scans and work your queue (Pro and Max), or untick it for a read-only connection.

4. In a chat, turn Cituna on from the + menu and ask your first question.

On Team and Enterprise plans an owner adds the connector once under Organization settings → Connectors, then each member connects it from Customize → Connectors and signs in with their own Cituna account. A connector added on claude.ai is also available in Claude Desktop and the mobile apps signed in to the same account.

Claude Desktop

The connector above is the quickest route: Customize → Connectors → Add → Add custom connector, paste https://mcp.cituna.com/mcp, and approve in the browser.

To run the npm package locally instead, generate an API key (below) and edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "cituna": {
      "command": "npx",
      "args": ["-y", "cituna-mcp"],
      "env": {
        "CITUNA_API_KEY": "cituna_sk_your_generated_key"
      }
    }
  }
}

On Windows, if the server does not start, run npx through cmd: "command": "cmd" and "args": ["/c", "npx", "-y", "cituna-mcp"]. Restart Claude Desktop. The tools appear under the + button in the chat box.

Claude Code

Hosted, with browser sign-in:

claude mcp add --transport http cituna https://mcp.cituna.com/mcp

Then run /mcp inside Claude Code, pick cituna and choose Authenticate. To use an API key instead of OAuth:

claude mcp add --transport http cituna https://mcp.cituna.com/mcp \
  --header "Authorization: Bearer cituna_sk_your_generated_key"

Or run the npm package locally, available in every project:

claude mcp add cituna --scope user \
  --env CITUNA_API_KEY=cituna_sk_your_generated_key \
  -- npx -y cituna-mcp

Run /mcp to confirm it is connected, then ask "what changed in my AI visibility this week?"

ChatGPT

ChatGPT connects to the same hosted URL. Yes, you can ask ChatGPT how ChatGPT cites you.

1. In ChatGPT on the web, open Settings → Security and login and turn on Developer mode. It comes with Plus, Pro, Business, Enterprise and Edu.
2. Open Plugins, click +, then Create MCP App.
3. Name it Cituna, paste https://mcp.cituna.com/mcp, choose OAuth, and create it.
4. Sign in to Cituna and approve with Also allow changes ticked if you want writes. Then add Cituna to a chat from the + menu.

ChatGPT asks before each change. Reading works on Starter; scans and edits need Pro or Max. Approved ChatGPT connections are listed under Integrations in the Cituna app, where you can disconnect them.

Cursor

Or add it to ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "cituna": {
      "url": "https://mcp.cituna.com/mcp"
    }
  }
}

Cursor lists the server under its MCP settings with a sign-in button; click it, sign in to Cituna and approve. To skip OAuth, send your API key as a header:

{
  "mcpServers": {
    "cituna": {
      "url": "https://mcp.cituna.com/mcp",
      "headers": { "Authorization": "Bearer cituna_sk_your_generated_key" }
    }
  }
}

Or run it locally with "command": "npx", "args": ["-y", "cituna-mcp"] and "env": { "CITUNA_API_KEY": "cituna_sk_..." }. Use the tools from Cursor's agent chat.

VS Code (GitHub Copilot)

Or from the command line:

code --add-mcp '{"name":"cituna","type":"http","url":"https://mcp.cituna.com/mcp"}'

Or in .vscode/mcp.json for one workspace (run MCP: Open User Configuration from the Command Palette for all of them):

{
  "servers": {
    "cituna": {
      "type": "http",
      "url": "https://mcp.cituna.com/mcp"
    }
  }
}

VS Code opens the Cituna sign-in the first time a tool runs. To use an API key, let VS Code prompt for it once and keep it out of the file:

{
  "inputs": [
    { "type": "promptString", "id": "cituna-key", "description": "Cituna API key (cituna_sk_...)", "password": true }
  ],
  "servers": {
    "cituna": {
      "type": "http",
      "url": "https://mcp.cituna.com/mcp",
      "headers": { "Authorization": "Bearer ${input:cituna-key}" }
    }
  }
}

Open Copilot Chat in Agent mode and the Cituna tools appear in the tools picker.

Windsurf

In ~/.codeium/windsurf/mcp_config.json (or Windsurf's MCP settings, which open the same file):

{
  "mcpServers": {
    "cituna": {
      "serverUrl": "https://mcp.cituna.com/mcp"
    }
  }
}

If your Windsurf version does not open a browser sign-in, add "headers": { "Authorization": "Bearer cituna_sk_your_generated_key" } next to serverUrl.

Codex CLI

Run the npm package with your API key:

codex mcp add cituna --env CITUNA_API_KEY=cituna_sk_your_generated_key -- npx -y cituna-mcp

That writes the equivalent of this to ~/.codex/config.toml:

[mcp_servers.cituna]
command = "npx"
args = ["-y", "cituna-mcp"]
env = { CITUNA_API_KEY = "cituna_sk_your_generated_key" }

Gemini CLI

gemini mcp add --transport http cituna https://mcp.cituna.com/mcp

Then run /mcp auth cituna to sign in. Or in ~/.gemini/settings.json, with an API key instead of OAuth:

{
  "mcpServers": {
    "cituna": {
      "httpUrl": "https://mcp.cituna.com/mcp",
      "headers": { "Authorization": "Bearer cituna_sk_your_generated_key" }
    }
  }
}

Any other MCP client

• Supports remote servers: point it at https://mcp.cituna.com/mcp over Streamable HTTP. If it supports OAuth it discovers the sign-in on its own from the 401 challenge; if not, send Authorization: Bearer cituna_sk_... (or X-API-Key: cituna_sk_...).
• Supports stdio only: run npx -y cituna-mcp with CITUNA_API_KEY in its environment.

From source, for development:

git clone https://github.com/cituna/cituna-mcp && cd cituna-mcp
npm install && npm run build   # then: node dist/index.js

Getting an API key

The hosted connector does not need a key. The npm package and the header options do:

1. In the Cituna app, open Integrations → Claude / MCP access and click Generate token.
2. Copy the cituna_sk_... value. It is shown once.
3. Paste it into your client's config as above.

Keys do not expire on their own, are not your password, and can be revoked in the app at any time. The same key works for the Looker Studio connector and the REST API. Each person should use their own key: a key acts as one workspace, and nothing else.

Tools

31 tools: 22 read tools and 9 write tools. Reads work from Starter with one exception, list_keywords, which reads the keyword dataset that is part of Pro. The nine write tools need Pro or higher, and a connection approved without Also allow changes cannot call them on any plan. Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint), so a client can auto-approve reads and ask before a write; set_prompts, update_article and enrich_article are marked destructive because they can delete or overwrite.

Start here

Daily AI visibility tracking

Audits and the fix queue

Citation sources and competitors

Google Search Console

Keywords and AutoSEO articles

Plans and access

The MCP server comes with every paid Cituna plan. There is no separate add-on and no free MCP tier: the 3-day free trial is app-only, and an ended trial with no plan cannot call the server.

How the gates behave:

• A write tool on Starter returns a plan message naming Pro, and changes nothing. On Starter you still run scans and work the queue in the app, just not from the agent.
• Writes need the scope as well as the plan. If you untick Also allow changes on the consent screen, the connection is read-only even on Pro or Max. To add writes later, disconnect it under Integrations and connect again with the box ticked.
• The monthly MCP-call allowance counts every call. A used-up allowance comes back as a plan-limit message (HTTP 402); upgrade or wait for the period to reset. HTTP 429 is a separate burst limit: wait the seconds it names and retry.
• run_scan spends a scan from the monthly allowance, and scanning a domain you do not track adds it as a brand against your plan's brand cap. Everything else reads data Cituna already collected.
• enrich_article uses one generation from the monthly allowance and changes a live page on your site.

A custom Enterprise plan lifts the limits further, with invoiced billing. Full limits per plan: cituna.com/pricing.

Built-in workflows

The server ships five analysis workflows through the MCP prompts API. In Claude they show up in the prompt picker; in any client, the server's instructions tell the agent which workflow answers which question, so plain English routes itself. Each one joins Search Console data with the engines' actual answer text, which a generic SEO tool cannot do.

None of them starts a paid scan on its own.

What a session looks like

An example first conversation, once the server is connected (acme.com stands in for your brand):

You: We sell scheduling software. Why does ChatGPT never mention us?

Claude: (whoami → Pro, 4 of 15 scans used · list_brands → acme.com · gsc_status → connected) Running the not-cited diagnosis on acme.com.

(get_visibility) You are cited in 3 of 18 prompt×engine cells. ChatGPT answers all six of your category prompts and cites you in none of them.

(get_engine_answers on the 3 biggest) For "best scheduling software for clinics" ChatGPT cites Calendly, Acuity and a Capterra roundup. Every citation is a third-party list. Not one is a vendor's own site, including your rivals'.

(gsc_query) Google already sends you 1,240 impressions for that intent at average position 8.4. So this is not an indexation problem.

The finding: you are Google-visible and AI-invisible. ChatGPT builds that answer out of roundups you are absent from, so no amount of on-site work moves it. The lever is getting into those lists.

(list_keywords stage:"none") "scheduling software for clinics" has demand and no page behind it. Want me to queue it? (queue_article)

Nothing above spends a scan: it is all reads over data Cituna already collected.

Connecting Google Search Console

The gsc_* tools need a one-time connect in the Cituna app, not in your MCP client. There is no Google OAuth in this server, by design: the browser consent happens in the app, and the refresh token is stored server-side only.

1. In the app, open Integrations and click Connect Google Search Console (paid plans).
2. Google asks to grant Cituna read-only Search Console access (webmasters.readonly). Cituna never gets write access to anything at Google.
3. Pick the Google account where your domain is a verified Search Console property. This is the step people miss: if that account has never verified the domain, everything connects and every query still comes back empty, because Google has nothing to show it.
4. Back in your agent, run gsc_status. It lists each connected account and every property it can query. If your domain is not there, verify the property in Search Console, not in Cituna.

A workspace can connect several Google accounts, and a domain is readable when any of them holds a property for it. Disconnecting in the app (Integrations, Disconnect) cuts off this server at once.

Authentication and security

The server is a thin client over the Cituna API. It holds no Google credentials and no database: it sends your Cituna credential to the backend, which looks up your workspace's stored Search Console refresh token, mints a short-lived Google access token, and queries Google for you.

OAuth (the hosted connector). The server is an OAuth 2.1 protected resource and the Cituna API is the authorization server. A client walks the chain itself:

POST /mcp  (no credential)
  → 401 + WWW-Authenticate: Bearer resource_metadata="…"
      → GET https://mcp.cituna.com/.well-known/oauth-protected-resource
          → names https://api.cituna.com as the authorization server
              → GET  /.well-known/oauth-authorization-server
              → POST /oauth/register     (dynamic client registration, RFC 7591)
              → GET  /oauth/authorize    (browser: sign in, then consent)
              → POST /oauth/token        (PKCE S256 required)

Clients can also sign in with a published client identity (client ID metadata documents), which is how Claude and ChatGPT connect. Access tokens last 24 hours. Refresh tokens rotate on every use, and a rotated-out refresh token presented again ends the whole connection, so a stolen copy cannot quietly outlive the real client. There are two scopes, cituna:read and cituna:write, and a write tool needs the scope and the plan.

API keys. A cituna_sk_... key goes in CITUNA_API_KEY for the npm package, or in an Authorization: Bearer (or X-API-Key) header for the hosted URL. A key authenticates as one workspace only, and the hosted server is stateless per request, so keys never mix. Do not wire a gateway to send one shared key for all of its users: every one of them would act as that single workspace.

What a connection cannot do. It can call the MCP tools and nothing else. It cannot create API keys, change your password, reach billing, invite teammates, or approve another app; those need you signed in to the app. Tokens are only issued for Cituna's own MCP server (RFC 8707 resource), so another server that names Cituna as its authorization server cannot collect one.

Third-party content. Answer text, cited titles, URLs and Search Console queries are quoted from AI engines, the pages they read and the people who search. The server tells your agent to treat them as data and never to follow instructions found in them, or call a write tool because tool output asked it to.

Approved apps are listed under Integrations in the app, each marked read-only or able to make changes, and can be disconnected there.

Self-hosting the remote server

The hosted URL is the same code as this repository. Both transports are built from one tool layer (src/tools.ts), so the tool list, descriptions and schemas are literally the same objects, and npm run test:transports fails the build if they ever diverge.

The stdio server reads CITUNA_API_URL (backend base URL, default https://cituna.com) plus one credential, checked in this order: CITUNA_API_KEY (recommended), CITUNA_TOKEN (a session token from the app, which expires after about 30 days), or CITUNA_EMAIL with CITUNA_PASSWORD (the server logs in and refreshes on expiry).

Run the remote server:

npm run build && npm run start:http    # or: npm run dev:http

There is no CITUNA_API_KEY here, deliberately: the remote server holds no credential of its own. Every request carries its own, a fresh client and MCP server are built for it, and both are torn down when the response ends, so one user's key can never be captured into another user's session. A request with no credential gets 401 and cannot even list the tools. Deploy with the included Dockerfile (multi-stage; the runtime image carries one production dependency). If you self-host on a domain outside cituna.com, add its origin to OAUTH_ALLOWED_RESOURCES on the API so it can be issued tokens (loopback addresses are always allowed).

Endpoints on the remote server:

Directories and gateways. The official MCP Registry entry (server.json, com.cituna/cituna-mcp) carries a remotes entry that tells registry-driven clients, and directories that mirror the registry such as PulseMCP and Glama, to connect directly to https://mcp.cituna.com/mcp and prompt for a personal API key. Nothing is routed through the directory.

Versions. The hosted URL always runs the newest release, and npx -y cituna-mcp fetches the newest one from npm. Pin a version with npx -y cituna-mcp@<version>; the npm badge above shows the current one, and GET /healthz reports what the hosted server runs.

Troubleshooting

FAQ

What is the Cituna MCP server? A Model Context Protocol server that connects your Cituna workspace to an AI agent. It reads your daily AI visibility tracking, the engine answers behind it, the pages engines cite, your audits, fix queue, keywords, AutoSEO articles and live Search Console data, and on Pro it can act: run a scan, change the prompts you track, move a fix along, queue, edit or refresh an article, and log outreach.

Which AI engines does it cover? Seven, all checked daily: ChatGPT, Perplexity, Gemini, Claude, Grok, Google AI Overviews and Google AI Mode. Google AI Overviews and Google AI Mode are tracked separately because they give different answers to the same query. Microsoft Copilot is not tracked.

Does it work with ChatGPT? Yes. Turn on Developer mode, create an MCP app with the hosted URL and choose OAuth (steps above). Developer mode comes with ChatGPT Plus, Pro, Business, Enterprise and Edu, on the web.

Do I need to install anything? No. The hosted connector is a URL and a browser sign-in. Node 20 or later is only needed for the optional npm package.

Is there a free plan? No free MCP. The server comes with every paid plan from Starter ($49/mo), read-only there; write tools come with Pro. The 3-day free trial is app-only.

Can the agent change my data? Only on Pro or Max, only if you ticked Also allow changes when you approved it, and only through the nine write tools listed above. Clients that respect MCP annotations ask before each write, and ChatGPT always does.

Is my Google data safe? The server never sees your Google credentials. Cituna holds a read-only Search Console grant server-side and queries Google for you; disconnecting in the app cuts off the MCP at once.

Is Cituna the only AI visibility tool with an MCP server? No. Several AI visibility tools ship one, with different tools, plans and read or write access. Cituna's pairs daily tracking on seven engines with your Search Console data and AutoSEO writes, from $49. See the dated comparison at cituna.com/learn/ai-visibility-tools-with-mcp-server.

Is there a REST API too? Yes. The same data is available over HTTPS with a bearer token for your own dashboards, agents and CI. See cituna.com/developers.

Links

• Product page and docs: cituna.com/mcp
• Pricing and plan limits: cituna.com/pricing
• Connect, keys and approved apps (in the app): cituna.com/integrations
• REST API: cituna.com/developers
• AI visibility tools with an MCP server, compared: cituna.com/learn/ai-visibility-tools-with-mcp-server
• npm package: cituna-mcp
• Official MCP Registry: com.cituna/cituna-mcp
• Source mirror: github.com/cituna/cituna-mcp
• Bugs and requests: GitHub issues

Looker Studio connector

This repository also carries looker-connector/, a Google Apps Script community connector for Looker Studio dashboards on your Cituna visibility data. Deploy Code.gs as a community connector, paste your cituna_sk_... key on the KEY auth screen, and build dashboards. Full setup: looker-connector/README.md.

About this repository

This is a published mirror, not the working tree. Both integrations are developed in Cituna's private monorepo and released here automatically on tag, so the tool surface and the connector's engine list stay pinned to what the API actually serves.

Pull requests against this repo cannot be merged directly, but issues are read and acted on, so please do open them.

License

MIT licensed. Bugs and requests: https://github.com/cituna/cituna-mcp/issues