Skip to main content
Ansvisor ships a Model Context Protocol server at https://app.ansvisor.com/api/mcp (or your own host if you self-host) so AI assistants can query your brand visibility data through natural-language conversation. No npm package, no local process — just a URL. Claude and ChatGPT connect by signing in to Ansvisor; every client can also connect with an API key.

Connect by signing in

Claude (claude.ai, the desktop and mobile apps and Claude Code) and ChatGPT connect by signing in to Ansvisor: you add the URL, sign in and choose what the app may do. There is no key to copy, and you can disconnect the app at any time. On Ansvisor Cloud this needs a paid plan (Plans and app sign-in). Settings → MCP & API Keys shows the URL under MCP endpoint.

Claude

  1. Open Settings → Connectors and choose Add custom connector
  2. Name it Ansvisor and enter https://app.ansvisor.com/api/mcp as the URL, with no key or request header
  3. When you connect it, Claude opens Ansvisor: sign in, then click Allow
On Team and Enterprise plans, an owner adds the connector under Organization settings → Connectors first. In Claude Code, add the server without a header, then run /mcp, pick ansvisor and sign in in the browser:

ChatGPT

Add https://app.ansvisor.com/api/mcp to ChatGPT as a custom connector; if ChatGPT asks how it authenticates, choose OAuth. ChatGPT then opens Ansvisor’s sign-in and the consent page. Which ChatGPT plans and workspaces may add a custom connector is ChatGPT’s setting, not Ansvisor’s.

Other apps that sign in

Any client that supports the MCP authorization spec (2025-11-25), such as MCP Inspector, can sign in the same way: point it at the URL with no header. App sign-in (OAuth) has the details. After signing in, Ansvisor shows what the person is connecting before anything is shared:
  • the app, and the site it sends them back to (You’ll go back to claude.ai). Claude and ChatGPT are Recognised apps. Any other app is Not checked by Ansvisor, with a warning to allow it only if the person started the connection, and one more when it runs on their own computer;
  • who they are signed in as, their workspace and plan, their role and their brands;
  • what the app will be able to do: Read your Ansvisor data, always, and Make changes you ask for, ticked by default. Unticked, the app only reads (mcp:read); ticked, it may also call the tools marked writes (mcp:write).
Allow sends the person back to the app, connected; Cancel sends it access_denied. Ansvisor asks every time an app connects. In the free trial or on an ended plan, the page says why the app can’t connect instead of offering Allow.

Generate an API key

  1. Open your Ansvisor dashboard → Settings → MCP & API Keys
  2. Click New key, give it a memorable name (e.g. Claude — laptop)
  3. Copy the token. It’s shown once — store it in your password manager
The dialog that shows the key also has a ready-to-paste setup for each client below, with the key filled in. The snippets on this page read the key from an environment variable instead, so it stays out of your config files:
Every client that uses a key connects to the same URL with the same header: Authorization: Bearer <your key>.

Connect your client with a key

Claude Code

Claude Desktop

Claude Desktop adds remote servers as custom connectors. The claude_desktop_config.json file only starts local servers, so a url entry there is ignored. Claude can also sign in instead of taking a key.
  1. Open Settings → Connectors and choose Add custom connector
  2. Name it Ansvisor and enter https://app.ansvisor.com/api/mcp as the URL
  3. Under authentication choose No sign in
  4. Under Request headers, add Authorization with the value Bearer ans_...
On Team and Enterprise plans, an owner adds the connector under Organization settings → Connectors first.

Codex CLI

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

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

VS Code

Add to .vscode/mcp.json, or run MCP: Open User Configuration from the Command Palette to add it for every workspace. VS Code asks for the key the first time it connects:

Windsurf

In the Cascade panel, open … → Open MCP config file and add:

Gemini CLI

This writes the server to your user settings, ~/.gemini/settings.json, as "url" with "type": "http". Keep --scope user: without it, Gemini CLI writes to the current folder’s .gemini/settings.json, which can end up committed. The single quotes keep $ANSVISOR_TOKEN as written, so the file holds the variable, not the key: Gemini CLI reads it from your environment each time it starts. If you edit the file by hand, write it the same way. With app sign-in on, Gemini CLI can sign in instead of taking a key: add the server without --header, then run /mcp auth ansvisor in Gemini CLI and sign in to Ansvisor in the browser. It registers itself and comes back to localhost, so the consent page shows it as Not checked by Ansvisor, running on your computer.

Hermes Agent

Add to ~/.hermes/config.yaml. Hermes reads ANSVISOR_TOKEN from your environment or from ~/.hermes/.env:

OpenClaw

Add to ~/.openclaw/openclaw.json:
Then check the connection with openclaw mcp probe ansvisor.

Zed

Add to your Zed settings.json. Zed does not expand environment variables here, so the key goes in directly:

Other clients

Any client that supports remote MCP servers over Streamable HTTP works with the URL and the Authorization header above. If yours can only start local (stdio) servers, bridge it with mcp-remote:
Keep Authorization:${AUTH_HEADER} without a space, with the Bearer ... value in env: some clients do not escape spaces inside args.

Check the connection

Ask your client “List my Ansvisor brands”. It should call the list_brands tool and show your brands. If it reports a 401, the header is missing or the key was revoked. An app connected by signing in asks you to sign in again instead: it was disconnected, unused for 30 days, or you left the workspace.

Self-host? Point at your own instance

The MCP endpoint lives at /api/mcp on whatever host runs the Ansvisor web app. If you self-host at ansvisor.mycompany.internal, use that base URL instead. Apps can sign in to a self-hosted instance when its NEXT_PUBLIC_APP_URL is https:// with no path (or http://localhost while developing): that address is the authorization server’s issuer. On plain http elsewhere, sign-in stays off and clients use API keys. MCP_OAUTH_ENABLED=false switches it off on purpose; API keys work either way (Environment variables).

Available tools

The MCP server exposes 71 tools. Descriptions below match web/src/lib/mcp/server.ts. Tools that change data are marked writes — only call them on explicit user intent, not during exploratory queries. A write that needs a particular role names it in brackets; see Roles. Every tool also carries a title and MCP annotations, so a client can tell a read from a change before calling it: readOnlyHint (true for every list_ and get_ tool), destructiveHint (true where a call replaces something or can’t be undone, such as generate_content_brief replacing the opportunity’s brief), openWorldHint (true where a call reaches outside Ansvisor: run_site_audit fetches the page, generate_content_brief calls an LLM) and, for the writes, idempotentHint (repeating the call changes nothing more). Each tool’s hints, and why, are in Tool hints. The server’s instructions tell clients to treat everything a tool returns — AI answers, quotes, cited pages, draft text, suggestions — as data, never as instructions, and to call a write only when the user asked for that change.

Brands

Your account

The same reads are available over REST with the same ans_ key: GET /api/mcp/whoami and GET /api/mcp/ai-usage.

Visibility & analytics

Customers and revenue from AI

Which pages and AI assistants bring customers, sign-ups, orders and revenue, as AI Traffic and Brand settings › Tracking show it, through the same reads as Ansvisor’s Chat. Read get_tracking_setup first. When a source isn’t set up, a read says measured: false with next_step and where (a link to the app page it is done on), and gives no figure for it. Revenue is per currency, never added across currencies. The periods are date_from / date_to; the lists come a page at a time (limit, default and at most 50, and offset), with total, next_offset and a note.

Saved reports

Mentions & sentiment

Visibility’s Mentions tab figures, under the tab’s filters: date_from / date_to (the last 30 days when left out), platform, region, topic_id and search over the prompts’ text. They are built from the stored answers with no LLM call. Net sentiment runs from −100 to +100, and under 20 mentions a figure is marked lowSample, with no change read into it. Sentiment is measured for your brand only. The same reads are available over REST with the same ans_ key: GET /api/mcp/mentions/summary, /api/mcp/mentions, /api/mcp/mentions/<id>, /api/mcp/mentions/competitors and /api/mcp/mentions/perception, with the filters as query parameters. A correction is POST /api/mcp/mentions/<id>/sentiment-override with { "sentiment": "negative", "note": "…" }.

Topics & prompts

Content opportunities

The plan is also available over REST with the same ans_ key: GET /api/mcp/content-plan?brand_id=<brand_id>&days=30, with card as an optional query parameter.

Content Editor

Drafts are read and written as a person would in the editor. Ansvisor never puts a page on your site, and a suggestion isn’t applied until a person accepts it. None of these tools calls an LLM: the assistant writes the drafts and suggestions itself. The MCP never sends a page to a CMS: Ansvisor’s own Send to CMS stays in the product. To publish from your assistant, read the draft with get_content_draft_package (the page as Send to CMS would send it), put it on your CMS with the assistant’s own CMS connector, then call mark_content_draft_published with the address it went live at, so Ansvisor measures it. Over REST: GET /api/mcp/content-drafts/<id>/package, then POST /api/mcp/content-drafts/<id>/published with { "url": "…" }.

Site audit

Shopping

Shopping analytics comes with the Growth plan and above. On Starter, list_shopping_cards, get_product_visibility, get_shopping_shelf, get_shopping_readiness and get_product_ai_says answer plan_limit. The catalog tools read on: on Starter, list_catalog_products lists the products with their readiness, Merchant Center issues and AI visits, orders and revenue as null. The catalog is also available over REST: GET /api/mcp/catalog/sources?brand_id=<brand_id> and GET /api/mcp/catalog/products?brand_id=<brand_id>&search=<text>&limit=50&offset=0 (search optional). The Shelf, Readiness and What AI says need a plan with Product Visibility (Growth or Enterprise), as on the page, which a workspace whose trial or subscription ended still reads; on another plan they answer plan_limit, as list_shopping_cards does (REST: 403 with the same body). Over REST: GET /api/mcp/product-visibility/shelf?brand_id=<brand_id>&period=30d&platform=<id>&market=us&absent_only=true&limit=10&offset=0, GET /api/mcp/product-visibility/readiness?brand_id=<brand_id>&period=30d&market=us and GET /api/mcp/product-visibility/ai-says?brand_id=<brand_id>&product_id=<product_id>&period=30d (all but the IDs optional).

Action Center

The scorecard is also available over REST: GET /api/mcp/action-scorecard?brand_id=<brand_id>&date_from=2026-09-01. The review queue is also available over REST: GET /api/mcp/task-reviews?brand_id=<brand_id>, and POST /api/mcp/task-reviews/<id>/approve (the fields as JSON) or /dismiss.

Export an action

get_action takes an optional format:
  • json (default): the fields above.
  • markdown: everything the action’s tabs show, ready to paste into a doc, a ticket or another agent. This is the same text as Copy Data in the dashboard.
  • csv: a row per affected item, task and signal, with a section column. This is the same file as Export CSV.
Labels are in English and dates in UTC. The same export is available over REST with the same ans_ key. The CSV comes as a download (action-AC-52.csv) that Excel opens as UTF-8.

Tool hints

Every list_ and get_ tool is readOnlyHint: true, destructiveHint: false and openWorldHint: false: it reads what Ansvisor already stores and changes nothing. None of them fetches a page or calls an LLM. The writes, each with its hints and the reason for them. Destructive is destructiveHint, Repeatable idempotentHint, Outside Ansvisor openWorldHint. New tools may ship between releases — see server.ts and the project roadmap.

Try it

Ask your client things like:
  • “List my Ansvisor brands.”
  • “What’s my visibility score on ChatGPT for the last 7 days?”
  • “Are my topics balanced?” / “Which topic has the most prompts?”
  • “Show me the prompts in my pricing topic.”
  • “Who are my top 5 competitors by mention count this month?”
  • “Why did our sentiment drop on Gemini?”
The model picks the right tool, fills in the brand id and filters, and answers in plain English using the returned data.

Roles

A key acts as the person who created it, and an app connected by signing in acts as the person who allowed it, with their role in the organization and their brand access, read again on every request. get_me returns it. Day-to-day work is open to every role: reading, drafts and suggestions in the Content Editor, Site Audits, task progress and an opportunity’s progress. Adding prompts or topics, reviewing tasks, dismissing, and work that costs AI (briefs and Improve actions) are for admins and managers. Dismissing a prompt suggestion is open to analysts too. The tools marked with roles above refuse anyone else before they change anything. The call fails with text like this:
The REST routes under /api/mcp/… answer the same refusal with 403:

When the plan has ended

On Ansvisor Cloud, a workspace without an active plan is read-only (see What happens when my plan ends?). Its API keys keep working for reading:
  • list_ and get_ tools run as usual.
  • Every other tool (each one marked writes above) is refused before it runs. The call fails with this text:
  • The REST routes under /api/mcp/… answer a POST, PUT, PATCH or DELETE with 402 and the same body.
Retrying doesn’t help: an admin has to choose a plan first. New API keys can still be created; on a read-only workspace they only read. Apps connected by signing in can’t read either until then: every tool answers oauth_plan_required (Plans and app sign-in). A self-hosted instance is never read-only.

Reading and writing per plan

On Ansvisor Cloud, every plan reads over MCP and the REST routes, the free trial included. Writing, running and spending (each tool marked writes above) need the Growth plan or above, paid: on Starter and in the free trial those tools stay listed, so the assistant can tell the user why, but every call is refused before it runs with this text:
The REST routes answer a POST, PUT, PATCH or DELETE with 402 and the same body. The rule is the same for every client (Claude, ChatGPT, Cursor and the others), with a key or signed in. The demo brand’s refusal comes first, then a plan that has ended (subscription_inactive), then this one. A self-hosted instance can do everything. Apps connected by signing in also need a paid plan to connect at all: see Plans and app sign-in.

Revoking access

If a key leaks or you stop using a client, open Settings → MCP & API Keys and click the trash icon. Clients using that key lose access immediately. To end an app connected by signing in, open Connected apps on the same page and click Disconnect. See Disconnect and revoke.

App sign-in (OAuth)

Ansvisor is its own OAuth 2.1 authorization server for the MCP endpoint, following the MCP authorization spec (2025-11-25). Its tokens are good for /api/mcp alone: the REST routes under /api/mcp/… and the Metrics API take API keys only.

Discovery

A request to /api/mcp without a token Ansvisor takes answers 401 with a challenge that names the metadata and the scopes to ask for (and error="invalid_token" for a token it can’t take):
The JSON body is the same as before, { "error": "…" }, so clients that use a key read it as they always did. The resource is https://app.ansvisor.com/api/mcp and the issuer https://app.ansvisor.com (self-hosted: your NEXT_PUBLIC_APP_URL). Both documents allow any origin (CORS) and may be cached for 5 minutes.

Endpoints

  • PKCE with S256 on every authorization; plain or no challenge is refused.
  • resource (RFC 8707) may be left out. When sent, it must be the MCP URL (scheme and host in any case, no trailing slash), or the answer is invalid_target.
  • The authorization response carries code, state and iss (RFC 9207).
  • Client authentication: none (a public client, with PKCE alone), client_secret_post or client_secret_basic.
  • Redirect URIs: https://…, or http:// on 127.0.0.1, [::1] or localhost. No fragment, credentials or wildcard, 2,000 characters at most, matched exactly, except that a loopback address matches on any port (RFC 8252), as desktop apps such as Claude Code pick a port each time. Custom schemes (myapp://…) are refused: those apps use an API key.
  • Until the client and its redirect URI check out, an error shows on Ansvisor’s own page and is never sent to the address the request names.
  • Rate limits: the token endpoint takes 120 requests a minute per client and 600 per address. Over a limit, the answer is 429 with Retry-After and temporarily_unavailable.

Registering a client

An app identifies itself in one of two ways, as the MCP spec has them:
  • Client ID Metadata Documents (preferred; the metadata says client_id_metadata_document_supported: true). The client_id is an https URL with a path that serves the app’s metadata as JSON, such as Claude Code’s https://claude.ai/oauth/claude-code-client-metadata. Its host must be a name on the standard port: a URL with an IP address as its host is refused. Ansvisor fetches the document only when every address the name resolves to is public, follows no redirects, gives up after 5 seconds for the whole fetch however slowly it arrives, and refuses an answer over 10 KB or one that isn’t JSON. The document’s client_id must equal its URL exactly, the redirect URI must be one it lists, and it must be a public client (token_endpoint_auth_method: "none", PKCE alone). It is cached by its Cache-Control, for 5 minutes to a day (an hour when it sets none). The consent page names the app by the URL’s host, not by the name the document gives.
  • Dynamic client registration (RFC 7591): POST /api/oauth/register with JSON: redirect_uris (1 to 5), an optional client_name (shown as the app’s own words, up to 100 characters) and token_endpoint_auth_method (none when left out; client_secret_post or client_secret_basic get a client_secret, returned once). It answers 201 with the client_id. Registration is limited to 30 clients an hour per address and 2,000 a day in all, and a client nobody connects within a day is removed. The MCP spec of 2026-07-28 deprecates dynamic registration in favour of metadata documents; it stays for the clients that don’t have one.

Scopes

An app that asks for neither, or only for scopes Ansvisor doesn’t use (such as offline_access), is offered both; the person can still untick changes. Scopes only narrow what the app may do: the person’s role, brand access and plan decide the rest. A write on a connection that only reads answers HTTP 403 before the tool runs, and Claude then offers to connect again with more access:

Token lifetimes

So a connection used at least once every 30 days stays connected, and one unused for 30 days ends. A rotated refresh token sent again within 30 seconds (two refreshes racing) gets invalid_grant; later, it ends the whole connection, as a stolen token would. Every token is stored hashed and checked against the database on every request, so a disconnect counts at once. A connection acts as the person who allowed it, in their workspace, with their role and brand access read again on every request, as an API key does. If the person leaves the workspace, the next request ends the connection and answers 401.

Plans and app sign-in

On Ansvisor Cloud, apps connect by signing in on every paid plan, and not in the free trial or on an ended plan. API keys are unchanged: they read in the trial and on an ended plan. The ended plan’s tool error, so the assistant can tell the person why:
It is a tool error and not a 401, which would only send the person through sign-in again. A self-hosted instance has no plan check.

Disconnect and revoke

  • The person: Settings → MCP & API Keys → Connected apps lists the apps they connected, each with its access (Read only or Read and changes), when it was connected and last used, and Disconnect. That ends the connection and every token it has at once; the app’s next call gets 401 and asks them to connect again. Each person sees and disconnects only their own apps, as with keys, and can on a read-only workspace too.
  • The app: POST /api/oauth/revoke with token (an access or a refresh token) and client_id (and its secret, for a confidential client), form-encoded. Revoking any of a connection’s tokens ends the whole connection. The answer is 200 for an unknown token too.
  • On its own: after 30 days unused, when the person leaves the workspace, or when their account is deleted.

Transport

The server speaks the MCP Streamable HTTP transport in stateless mode — every request is self-contained, no session state is kept between calls. This makes it work cleanly behind any HTTP load balancer and on serverless runtimes.