Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

feat(mcp): ready-to-paste setup for ten MCP clients (#903)

Gökhan Geyika18d61c7d9bf
diff --git a/docs/guides/mcp-server.mdx b/docs/guides/mcp-server.mdx
index e306a1ecb..0a6d46406 100644
--- a/docs/guides/mcp-server.mdx
+++ b/docs/guides/mcp-server.mdx
@@ -1,6 +1,6 @@
---
title: "MCP server"
-description: "Connect Claude Desktop, Claude Code, Cursor, Zed, and any MCP-aware client to your Ansvisor data — zero install."
+description: "Connect Claude, Codex, Cursor, VS Code, Gemini CLI, Hermes Agent, OpenClaw and any MCP-aware client to your Ansvisor data — zero install."
---
Ansvisor ships a [Model Context Protocol](https://modelcontextprotocol.io)
@@ -15,34 +15,203 @@ and an API key.
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
-## Connect Claude Desktop
+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:
-Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
-(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+```bash
+export ANSVISOR_TOKEN=ans_...
+```
+
+Every client connects to the same URL with the same header:
+`Authorization: Bearer <your key>`. There is no OAuth sign-in.
+
+## Connect your client
+
+### Claude Code
+
+```bash
+claude mcp add --transport http ansvisor https://app.ansvisor.com/api/mcp \
+ --header "Authorization: Bearer ${ANSVISOR_TOKEN}"
+```
+
+### 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.
+
+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
+
+```bash
+codex mcp add ansvisor --url https://app.ansvisor.com/api/mcp \
+ --bearer-token-env-var ANSVISOR_TOKEN
+```
+
+Or add it to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.ansvisor]
+url = "https://app.ansvisor.com/api/mcp"
+bearer_token_env_var = "ANSVISOR_TOKEN"
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
```json
{
"mcpServers": {
"ansvisor": {
"url": "https://app.ansvisor.com/api/mcp",
- "headers": {
- "Authorization": "Bearer ans_..."
- }
+ "headers": { "Authorization": "Bearer ${env:ANSVISOR_TOKEN}" }
}
}
}
```
-Restart Claude Desktop. Type _"List my Ansvisor brands"_ — Claude should
-call the `list_brands` tool and show your brands inline.
+### VS Code
-## Connect Claude 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:
+
+```json
+{
+ "inputs": [
+ {
+ "type": "promptString",
+ "id": "ansvisor-token",
+ "description": "Ansvisor API key",
+ "password": true
+ }
+ ],
+ "servers": {
+ "ansvisor": {
+ "type": "http",
+ "url": "https://app.ansvisor.com/api/mcp",
+ "headers": { "Authorization": "Bearer ${input:ansvisor-token}" }
+ }
+ }
+}
+```
+
+### Windsurf
+
+In the Cascade panel, open **… → Open MCP config file** and add:
+
+```json
+{
+ "mcpServers": {
+ "ansvisor": {
+ "serverUrl": "https://app.ansvisor.com/api/mcp",
+ "headers": { "Authorization": "Bearer ${env:ANSVISOR_TOKEN}" }
+ }
+ }
+}
+```
+
+### Gemini CLI
```bash
-claude mcp add ansvisor --transport http https://app.ansvisor.com/api/mcp \
- --header "Authorization: Bearer ans_..."
+gemini mcp add --transport http \
+ --header "Authorization: Bearer ${ANSVISOR_TOKEN}" \
+ ansvisor https://app.ansvisor.com/api/mcp
+```
+
+This writes the server to `~/.gemini/settings.json` with `httpUrl`. Use
+`httpUrl`, not `url`, if you edit the file by hand: `url` means the older SSE
+transport.
+
+### Hermes Agent
+
+Add to `~/.hermes/config.yaml`. Hermes reads `ANSVISOR_TOKEN` from your
+environment or from `~/.hermes/.env`:
+
+```yaml
+mcp_servers:
+ ansvisor:
+ url: "https://app.ansvisor.com/api/mcp"
+ headers:
+ Authorization: "Bearer ${ANSVISOR_TOKEN}"
+```
+
+### OpenClaw
+
+Add to `~/.openclaw/openclaw.json`:
+
+```json
+{
+ "mcp": {
+ "servers": {
+ "ansvisor": {
+ "url": "https://app.ansvisor.com/api/mcp",
+ "transport": "streamable-http",
+ "headers": { "Authorization": "Bearer ${ANSVISOR_TOKEN}" }
+ }
+ }
+ }
+}
+```
+
+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:
+
+```json
+{
+ "context_servers": {
+ "ansvisor": {
+ "url": "https://app.ansvisor.com/api/mcp",
+ "headers": { "Authorization": "Bearer ans_..." }
+ }
+ }
+}
```
+### 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`](https://github.com/geelen/mcp-remote):
+
+```json
+{
+ "mcpServers": {
+ "ansvisor": {
+ "command": "npx",
+ "args": [
+ "-y", "mcp-remote", "https://app.ansvisor.com/api/mcp",
+ "--header", "Authorization:${AUTH_HEADER}",
+ "--transport", "http-only"
+ ],
+ "env": { "AUTH_HEADER": "Bearer ans_..." }
+ }
+ }
+}
+```
+
+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.
+
## Self-host? Point at your own instance
The MCP endpoint lives at `/api/mcp` on whatever host runs the Ansvisor web
diff --git a/web/messages/en.json b/web/messages/en.json
index 8ad883c7b..d83a62785 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -2105,7 +2105,7 @@
"remove": "Remove",
"apiKeys_description": "Long-lived tokens for the Ansvisor MCP server and other external clients. Keys are shown once at creation — store them somewhere safe.",
"apiKeys_mcpEndpoint": "MCP endpoint",
- "apiKeys_mcpEndpointHint": "Paste this URL + a key below into Claude Desktop / Claude Code / Cursor. See the <link>MCP guide</link>.",
+ "apiKeys_mcpEndpointHint": "Create a key to get a ready-to-paste setup for Claude, Codex, Cursor and other MCP clients. See the <link>MCP guide</link>.",
"apiKeys_noKeys": "No API keys yet. Create one to connect the MCP server.",
"apiKeys_revoked": "revoked",
"apiKeys_created": "Created {date} · Last used {lastUsed}",
@@ -2117,6 +2117,21 @@
"apiKeys_copyTitle": "Copy your API key",
"apiKeys_copyDescription": "You won't be able to see this again. Store it somewhere safe.",
"apiKeys_done": "Done",
+ "apiKeys_connectTitle": "Connect a client",
+ "apiKeys_copySnippet": "Copy setup",
+ "apiKeys_connectHint": "The setup includes this key, so copy it now. The <link>MCP guide</link> shows how to keep the key in an environment variable instead.",
+ "apiKeysConnectWhere": {
+ "claude-code": "Run in your terminal.",
+ "claude-desktop": "In Claude, open Settings → Connectors → Add custom connector and fill in these fields.",
+ "codex": "Add to ~/.codex/config.toml.",
+ "cursor": "Add to ~/.cursor/mcp.json, merging into any existing mcpServers.",
+ "vscode": "Add to .vscode/mcp.json, or run \"MCP: Open User Configuration\" for every workspace.",
+ "windsurf": "In the Cascade panel, open … → Open MCP config file and merge this in.",
+ "gemini-cli": "Run in your terminal.",
+ "hermes": "Add to ~/.hermes/config.yaml.",
+ "openclaw": "Add to ~/.openclaw/openclaw.json, merging into any existing mcp.servers.",
+ "zed": "Add to your Zed settings.json."
+ },
"apiKeys_name": "Name",
"agent_description": "Bring your own Anthropic API key. The in-product agent uses your key to call Claude directly — usage is billed to your Anthropic account, not to Ansvisor.",
"agent_keyConfigured": "Key configured",
diff --git a/web/src/components/settings/api-keys-section.tsx b/web/src/components/settings/api-keys-section.tsx
index ba988bf86..9601886dc 100644
--- a/web/src/components/settings/api-keys-section.tsx
+++ b/web/src/components/settings/api-keys-section.tsx
@@ -17,9 +17,23 @@ import {
} from '@/components/ui/dialog';
import { Skeleton } from '@/components/ui/skeleton';
import { Badge } from '@/components/ui/badge';
+import {
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from '@/components/ui/select';
import { Copy, KeyRound, Loader2, Plus, Trash2 } from 'lucide-react';
import { useTranslations } from 'next-intl';
import { formatDate } from '@/lib/format';
+import { siteConfig } from '@/config/site';
+import {
+ MCP_CLIENTS,
+ MCP_CLIENT_LABELS,
+ mcpClientSnippet,
+ type McpClient,
+} from '@/lib/mcp/client-setup';
interface ApiKey {
id: string;
@@ -37,6 +51,10 @@ function getMcpEndpoint(): string {
return `${appUrl}/api/mcp`;
}
+const MCP_GUIDE_URL = `${siteConfig.links.docs}/guides/mcp-server`;
+
+const CLIENT_OPTIONS = MCP_CLIENTS.map((value) => ({ value, label: MCP_CLIENT_LABELS[value] }));
+
export function ApiKeysSection() {
const t = useTranslations('settings');
const tCommon = useTranslations('common');
@@ -48,6 +66,7 @@ export function ApiKeysSection() {
const [revealedToken, setRevealedToken] = useState<string | null>(null);
const mcpEndpoint = getMcpEndpoint();
const [confirmRevoke, setConfirmRevoke] = useState<string | null>(null);
+ const [client, setClient] = useState<McpClient>('claude-code');
const load = useCallback(async () => {
setLoading(true);
@@ -118,7 +137,7 @@ export function ApiKeysSection() {
<div>
<CardTitle className="flex items-center gap-2">
<KeyRound className="h-4 w-4" />
- {t('apiKeys_title')}
+ {t('apiKeys')}
</CardTitle>
<CardDescription>{t('apiKeys_description')}</CardDescription>
</div>
@@ -145,12 +164,7 @@ export function ApiKeysSection() {
<p className="text-muted-foreground">
{t.rich('apiKeys_mcpEndpointHint', {
link: (chunks) => (
- <a
- href="https://github.com/ansvisor/ansvisor#whats-next"
- target="_blank"
- rel="noreferrer"
- className="underline"
- >
+ <a href={MCP_GUIDE_URL} target="_blank" rel="noreferrer" className="underline">
{chunks}
</a>
),
@@ -287,6 +301,53 @@ export function ApiKeysSection() {
</Button>
</div>
</div>
+ {revealedToken && (
+ <div className="space-y-2 border-t pt-4">
+ <div className="flex items-center justify-between gap-3">
+ <p className="text-sm font-medium">{t('apiKeys_connectTitle')}</p>
+ <Select
+ items={CLIENT_OPTIONS}
+ value={client}
+ onValueChange={(v) => v && setClient(v as McpClient)}
+ >
+ <SelectTrigger size="sm" className="w-40">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {CLIENT_OPTIONS.map((opt) => (
+ <SelectItem key={opt.value} value={opt.value}>
+ {opt.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ </div>
+ <p className="text-xs text-muted-foreground">{t(`apiKeysConnectWhere.${client}`)}</p>
+ <div className="relative">
+ <pre className="max-h-56 overflow-auto rounded-md border bg-muted/40 p-3 pr-10 font-mono text-xs whitespace-pre">
+ {mcpClientSnippet(client, mcpEndpoint, revealedToken)}
+ </pre>
+ <Button
+ size="sm"
+ variant="ghost"
+ className="absolute right-1 top-1 h-7 px-2"
+ onClick={() => copy(mcpClientSnippet(client, mcpEndpoint, revealedToken))}
+ aria-label={t('apiKeys_copySnippet')}
+ >
+ <Copy className="h-3.5 w-3.5" />
+ </Button>
+ </div>
+ <p className="text-xs text-muted-foreground">
+ {t.rich('apiKeys_connectHint', {
+ link: (chunks) => (
+ <a href={MCP_GUIDE_URL} target="_blank" rel="noreferrer" className="underline">
+ {chunks}
+ </a>
+ ),
+ })}
+ </p>
+ </div>
+ )}
<DialogFooter>
<Button onClick={() => setRevealedToken(null)}>{t('apiKeys_done')}</Button>
</DialogFooter>
diff --git a/web/src/lib/mcp/client-setup.test.ts b/web/src/lib/mcp/client-setup.test.ts
new file mode 100644
index 000000000..ccd351755
--- /dev/null
+++ b/web/src/lib/mcp/client-setup.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { MCP_CLIENTS, mcpClientSnippet } from './client-setup';
+
+const URL_ = 'https://app.example.com/api/mcp';
+const TOKEN = 'ans_test123';
+
+describe('mcpClientSnippet', () => {
+ it.each(MCP_CLIENTS)('%s carries the endpoint and the bearer header', (client) => {
+ const snippet = mcpClientSnippet(client, URL_, TOKEN);
+ expect(snippet).toContain(URL_);
+ expect(snippet).toContain(`Bearer ${TOKEN}`);
+ });
+
+ it.each(['cursor', 'vscode', 'windsurf', 'openclaw', 'zed'] as const)(
+ '%s is valid JSON',
+ (client) => {
+ expect(() => JSON.parse(mcpClientSnippet(client, URL_, TOKEN))).not.toThrow();
+ },
+ );
+
+ it('uses each client’s own key for the server map and URL', () => {
+ const parse = (client: (typeof MCP_CLIENTS)[number]) =>
+ JSON.parse(mcpClientSnippet(client, URL_, TOKEN));
+
+ expect(parse('cursor').mcpServers.ansvisor.url).toBe(URL_);
+ expect(parse('vscode').servers.ansvisor).toMatchObject({ type: 'http', url: URL_ });
+ expect(parse('windsurf').mcpServers.ansvisor.serverUrl).toBe(URL_);
+ expect(parse('openclaw').mcp.servers.ansvisor).toMatchObject({
+ url: URL_,
+ transport: 'streamable-http',
+ });
+ expect(parse('zed').context_servers.ansvisor.url).toBe(URL_);
+ });
+});
diff --git a/web/src/lib/mcp/client-setup.ts b/web/src/lib/mcp/client-setup.ts
new file mode 100644
index 000000000..750e3d12f
--- /dev/null
+++ b/web/src/lib/mcp/client-setup.ts
@@ -0,0 +1,83 @@
+/**
+ * Copy-paste setup for the MCP clients people actually use, filled in with
+ * the endpoint and a freshly created key.
+ *
+ * Every format here was checked against the client's own documentation
+ * (October 2026); docs/guides/mcp-server.mdx carries the same snippets with
+ * the token read from an environment variable instead. The token is written
+ * inline because this is shown once, at creation, to someone who wants it
+ * working in one paste.
+ */
+
+export const MCP_CLIENTS = [
+ 'claude-code',
+ 'claude-desktop',
+ 'codex',
+ 'cursor',
+ 'vscode',
+ 'windsurf',
+ 'gemini-cli',
+ 'hermes',
+ 'openclaw',
+ 'zed',
+] as const;
+
+export type McpClient = (typeof MCP_CLIENTS)[number];
+
+export const MCP_CLIENT_LABELS: Record<McpClient, string> = {
+ 'claude-code': 'Claude Code',
+ 'claude-desktop': 'Claude Desktop',
+ codex: 'Codex CLI',
+ cursor: 'Cursor',
+ vscode: 'VS Code',
+ windsurf: 'Windsurf',
+ 'gemini-cli': 'Gemini CLI',
+ hermes: 'Hermes Agent',
+ openclaw: 'OpenClaw',
+ zed: 'Zed',
+};
+
+/** The snippet for one client. Where it goes (a terminal, a file, a settings
+ * screen) is UI copy and lives in messages under `apiKeysConnectWhere`. */
+export function mcpClientSnippet(client: McpClient, url: string, token: string): string {
+ const bearer = `Bearer ${token}`;
+ const json = (value: unknown) => JSON.stringify(value, null, 2);
+
+ switch (client) {
+ case 'claude-code':
+ return `claude mcp add --transport http ansvisor ${url} \\\n --header "Authorization: ${bearer}"`;
+ case 'claude-desktop':
+ return [
+ 'Name: Ansvisor',
+ `URL: ${url}`,
+ 'Authentication: No sign in',
+ `Request header: Authorization = ${bearer}`,
+ ].join('\n');
+ case 'codex':
+ return `[mcp_servers.ansvisor]\nurl = "${url}"\nhttp_headers = { "Authorization" = "${bearer}" }`;
+ case 'cursor':
+ return json({ mcpServers: { ansvisor: { url, headers: { Authorization: bearer } } } });
+ case 'vscode':
+ return json({
+ servers: { ansvisor: { type: 'http', url, headers: { Authorization: bearer } } },
+ });
+ case 'windsurf':
+ return json({
+ mcpServers: { ansvisor: { serverUrl: url, headers: { Authorization: bearer } } },
+ });
+ case 'gemini-cli':
+ return `gemini mcp add --transport http \\\n --header "Authorization: ${bearer}" \\\n ansvisor ${url}`;
+ case 'hermes':
+ return `mcp_servers:\n ansvisor:\n url: "${url}"\n headers:\n Authorization: "${bearer}"`;
+ case 'openclaw':
+ return json({
+ mcp: {
+ servers: {
+ ansvisor: { url, transport: 'streamable-http', headers: { Authorization: bearer } },
+ },
+ },
+ });
+ case 'zed':
+ return json({ context_servers: { ansvisor: { url, headers: { Authorization: bearer } } } });
+ }
+}