Connect AI Clients to Ayzeo (MCP Server)

"Using Ayzeo, show me my top 10 ACOS opportunities and explain why the number-one query scored so high."

"Which of my prompts have zero brand mentions in ChatGPT? What do competitors rank for those prompts?"

"Cross-reference my top ACOS opportunities with GA AI-referrer traffic. Pick the single best page to create and generate it."

"Compare sentiment across all tracked brands for my project. Which competitors have the strongest positive sentiment, and where are the sentiment gaps for Ayzeo?"

"Pro subscription required" error

The MCP server gates requests behind an active Pro or Enterprise subscription. Trial and Free/Starter accounts get this error. Upgrade from the pricing page to enable it.

gsc_not_connected / ga_not_connected

The tool you invoked requires a connected integration. The error payload includes a setupUrl — open it to finish the OAuth flow, then retry. After connecting, allow a few hours for the first sync to populate data.

gsc_sync_pending / ga_sync_pending

The integration is connected but the initial data sync hasn't populated yet. GSC imports up to 90 days on first sync — this can take a few minutes. Wait and retry.

"Rate limit exceeded"

The shared API rate limit is 100 requests per 5 minutes per token. An aggressive agent loop can burn through this. Wait 5 minutes for the window to reset, or create an additional token and split traffic.

Assistant can't see the tools

Restart the AI client after editing its config file. Verify the endpoint URL is exactly https://ayzeo.com/mcp/v1 (no trailing slash). Check that the bearer header is formatted Authorization: Bearer <token> with a space between Bearer and the token. If still failing, probe the endpoint with the MCP Inspector to isolate whether it's a server or client issue.

Claude Desktop: ReferenceError: File is not defined / Server transport closed unexpectedly

mcp-remote pulls in undici ≥ 7, which requires Node ≥ 20.18.1. If your OS launch PATH puts an older Node first (e.g. an old nvm default), Claude Desktop’s npx process loads undici under the old Node and crashes before the MCP handshake completes — even if you try to invoke a newer npx, the #!/usr/bin/env node shebang inside it re-resolves node via that same stale PATH. Two things are needed to fix it:

Step 1. Find the absolute path to a Node ≥ 20 install you already have. Pick whichever matches your setup:

• • nvm: nvm use 20 (or 22/24), then which node. Typical output: ~/.nvm/versions/node/v<VERSION>/bin/node.
• • Homebrew (macOS): brew --prefix node → typically /opt/homebrew/opt/node; binary at <prefix>/bin/node.
• • fnm / volta / asdf: fnm which 20, volta which node, or asdf which node.
• • System install: which node (after confirming node --version prints 20+).
• • Windows: where node in PowerShell; typically C:\Program Files\nodejs\node.exe.

Verify: run <node-path> --version and confirm it prints v20.-something or higher.

Step 2. Edit claude_desktop_config.json — pin the absolute path to npx in command, and pin PATH in env so the shebang re-resolves to the same Node. Replace <NODE_BIN_DIR> with the directory containing your Node binary from Step 1 (e.g. ~/.nvm/versions/node/v22.11.0/bin).

{
  "mcpServers": {
    "ayzeo": {
      "command": "<NODE_BIN_DIR>/npx",
      "args": [
        "-y", "mcp-remote",
        "https://ayzeo.com/mcp/v1",
        "--header", "Authorization: Bearer <your-token>"
      ],
      "env": {
        "PATH": "<NODE_BIN_DIR>:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
      }
    }
  }
}

On Windows, use the full path to npx.cmd for command and set env.PATH to the directory containing node.exe plus your usual %PATH% entries (semicolon-separated).

Step 3. Clear the npx cache if you ever launched mcp-remote under the broken Node — the cached install still has incompatible bits that the new Node will re-use if it finds them:

• • macOS / Linux: rm -rf ~/.npm/_npx
• • Windows: Remove-Item -Recurse -Force $env:APPDATA\npm-cache\_npx

Then fully quit Claude Desktop (Cmd+Q on macOS, right-click tray → Quit on Windows — not just close the window) and relaunch. If it still fails, reopen the log file referenced by Claude Desktop → Settings → Developer and confirm the new command path is actually being used.

Q: Can multiple AI clients share one token?

A: Yes, but creating one token per client is better for auditing and revocation. If a specific client leaks the token, you can revoke just that token without breaking the others.

Q: Does the MCP server work across multiple Ayzeo projects at once?

A: Each token (and therefore each MCP connection) is scoped to a single project. To work across multiple projects in the same AI client, register multiple MCP servers — one per project — with distinct names like ayzeo-brand-a and ayzeo-brand-b.

Q: Can I see which MCP tools the assistant called?

A: Most AI clients (Claude Desktop, Cursor, Claude Code) surface tool calls inline in the conversation. You can inspect each call, its arguments, and the returned payload. On the Ayzeo side, every call updates the token's lastUsedAt timestamp visible on the API Tokens page.

Q: Will the assistant hallucinate data?

A: All tools return real Ayzeo data — the MCP server never generates numbers. The assistant's narration ("this query scored 87 because...") is derived from the actual dimension scores returned by get_gsc_opportunities. If the assistant ever cites a number you can't find in the data, ask it to re-run the tool call with the filter you care about.

Q: Is there usage metering?

A: MCP calls share the WordPress API quota (100 requests per 5 minutes per token). Content-page generation counts against the project's 5-per-day content quota. Heavy AI-visibility prompt runs consume credits from your project's prompt allowance, same as running them from the dashboard.