# Connect AEO Copilot to your AI agent

This file is written for AI agents. If you are an AI agent reading this, your job is to connect AEO Copilot to the coding agent or assistant you are running in, then verify the connection works. Everything you need is on this page.

AEO Copilot (https://aeo-copilot.com) tracks how a brand shows up in AI-generated answers across ChatGPT, Claude, Perplexity, and Google AI Overview. It exposes that data 2 ways: an MCP server (preferred, works with Claude Code, Codex, Cursor, OpenCode, and any other MCP client) and a REST API (works everywhere else).

## Step 1: Get an API key from the user

You need an AEO Copilot API key. It starts with `aeo_`. Never invent one and never reuse a key from another service.

Ask the user for their key. If they do not have one yet, tell them how to create it:

1. Sign in at https://aeo-copilot.com and open Settings (gear icon, top right)
2. Pick the API tab
3. Name the key (for example "Claude Code") and hit Create
4. Copy the key now: the full key is only shown once

API and MCP access is included on every paid plan, starting with the $9/month Startup plan.

## Step 2: Install the MCP server

The MCP server is the npm package `aeo-copilot-mcp` (open source: https://github.com/sofianbettayeb/aeo-copilot-mcp). It runs locally over stdio via `npx` and needs Node.js 18 or newer. It reads the API key from the `AEO_COPILOT_API_KEY` environment variable.

Detect which agent you are running in and apply the matching setup. Replace `aeo_your_key_here` with the user's real key in every example.

### Claude Code

Run:

```bash
claude mcp add aeo-copilot -e AEO_COPILOT_API_KEY=aeo_your_key_here -- npx aeo-copilot-mcp
```

### Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.aeo-copilot]
command = "npx"
args = ["aeo-copilot-mcp"]
env = { "AEO_COPILOT_API_KEY" = "aeo_your_key_here" }
```

Then restart Codex.

### Cursor

Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in the project:

```json
{
  "mcpServers": {
    "aeo-copilot": {
      "command": "npx",
      "args": ["aeo-copilot-mcp"],
      "env": {
        "AEO_COPILOT_API_KEY": "aeo_your_key_here"
      }
    }
  }
}
```

### OpenCode

Add to `opencode.json` in the project (or the global OpenCode config):

```json
{
  "mcp": {
    "aeo-copilot": {
      "type": "local",
      "command": ["npx", "aeo-copilot-mcp"],
      "environment": {
        "AEO_COPILOT_API_KEY": "aeo_your_key_here"
      }
    }
  }
}
```

### Claude Desktop and other MCP clients

Any client that speaks MCP over stdio can use the same shape: command `npx`, args `["aeo-copilot-mcp"]`, env `AEO_COPILOT_API_KEY`. For Claude Desktop, put it under `mcpServers` in `claude_desktop_config.json` and restart the app.

## Step 3: Verify the connection

Call the `list_brands` tool. A working setup returns the brands on the user's account as JSON. If it errors:

- 401: the API key is wrong or was revoked. Ask the user to check it in Settings, API tab.
- Command not found / npx fails: Node.js 18+ is missing. Ask the user to install it.
- Tool not listed: the client did not pick up the config. Restart the agent or re-check the config file path.

## What you can do once connected

Read tools: `list_brands`, `list_topics`, `get_results` (per-prompt results across all 4 LLMs), `get_insights` (visibility score, sentiment, trends), `get_recommendations` (prioritized action items), `scan_brand` (technical AI-readiness scan).

Write tools: `create_brand`, `create_topic`, `add_prompts`, `update_prompt`, `update_prompts`, `run_brand_prompts` (runs the tracking across ChatGPT, Claude, Perplexity, and Google AI Overview).

Typical requests users make: "What's my brand's AI visibility score?", "Which prompts mention my competitors but not me?", "Run my prompts and summarize what changed", "Build an AI visibility report for my client".

## Fallback: the REST API

If MCP is not an option in your environment, the same data is available over REST. 26 endpoints, base URL `https://aeo-copilot.com/api/v1`, Bearer auth:

```bash
curl -H "Authorization: Bearer aeo_your_key_here" https://aeo-copilot.com/api/v1/brands
```

Core reads: `GET /brands`, `GET /brands/:id/topics`, `GET /brands/:id/results`, `GET /brands/:id/insights`, `GET /brands/:id/recommendations`. Writes cover brand creation, prompt management, runs, and scans. Full walkthrough: https://aeo-copilot.com/blog/how-to-connect-aeo-copilot-with-claude

## More context

- What AEO Copilot is, who it is for, pricing: https://aeo-copilot.com/llms-full.txt
- MCP server source and issues: https://github.com/sofianbettayeb/aeo-copilot-mcp
- Human-readable setup guide: https://aeo-copilot.com/blog/how-to-connect-aeo-copilot-with-claude