Connect OptAEO to your AI tools.

Overview

Model Context Protocol (MCP) is the open standard AI assistants use to talk to apps. OptAEO exposes an MCP endpoint at /api/mcp that speaks JSON-RPC 2.0. Connect Claude Desktop, Cursor, or VS Code via the bridge documented below and your assistant can read your Shopify catalog, pull AEO scores across ChatGPT / Perplexity / Gemini / Claude, run scans, and (Enterprise) apply fixes — directly from a chat window.

Sample prompts once connected

Plan tiers

MCP access starts on Business. See tier comparison.

Before you start

1. An OptAEO Business or Enterprise plan (free trial available). Sign in and check your plan badge in the sidebar.
2. One of Claude Desktop, Cursor, or VS Code installed on your machine.
3. Node.js with npx. Already installed if you have macOS Command Line Tools or any standard Node setup. The mcp-remote bridge package will auto-install on first run — no manual step.

Step 1 · Generate your MCP API key

1. Open OptAEO. Click Settings in the sidebar.
2. Click the Agent Mode tab in the tab strip.
3. Find the MCP Access card.
4. Click Generate Key. The plaintext key shows once in green — copy it immediately. We hash it server-side and never store the plaintext, so you cannot retrieve it later.
5. The key looks like: optk_mcp_aB3xY... (41 characters total). Paste it somewhere temporary — Notes, a TextEdit window — for the next step.

Key not what you expected? Click Revoke next to the key in Active Connections, then Generate Key again to get a fresh one.

Step 2A · Connect Claude Desktop

1. Find the config file.
   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Open it in any text editor. If it does not exist, create it with an empty JSON object {}.
3. Add the mcpServers block below. If the file already has other settings, add mcpServers alongside them — do not replace the whole file.

{
  "mcpServers": {
    "optaeo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://optaeo.ai/api/mcp",
        "--header",
        "Authorization:Bearer PASTE_YOUR_OPTAEO_MCP_KEY_HERE"
      ]
    }
  }
}

Replace PASTE_YOUR_OPTAEO_MCP_KEY_HERE with the key from Step 1. Keep the Bearer prefix and the surrounding quotes intact. Save the file.

4. Restart Claude Desktop fully. Cmd+Q on macOS — closing the window is not enough. Then relaunch from /Applications. First run installs mcp-remote via npx (~15 seconds, one-time).

Step 2B · Connect Cursor

Cursor's MCP config lives in ~/.cursor/mcp.json (user-level) or your project's .cursor/mcp.json (workspace). The format matches Claude Desktop almost exactly:

{
  "mcpServers": {
    "optaeo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://optaeo.ai/api/mcp",
        "--header",
        "Authorization:Bearer PASTE_YOUR_OPTAEO_MCP_KEY_HERE"
      ]
    }
  }
}

1. Replace PASTE_YOUR_OPTAEO_MCP_KEY_HERE with your key.
2. Save the file.
3. Cursor → Settings → Features → Model Context Protocol → confirm optaeo is listed and enabled.
4. Restart Cursor.

Step 2C · Connect VS Code

VS Code's MCP support (via the GitHub Copilot Chat extension) reads .vscode/mcp.json (workspace) or your global User settings. The schema uses servers rather than mcpServers, with an explicit type: "stdio" field:

{
  "servers": {
    "optaeo": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://optaeo.ai/api/mcp",
        "--header",
        "Authorization:Bearer PASTE_YOUR_OPTAEO_MCP_KEY_HERE"
      ]
    }
  }
}

1. Save as .vscode/mcp.json in your project root.
2. Replace PASTE_YOUR_OPTAEO_MCP_KEY_HERE with your key.
3. Open Copilot Chat (Ctrl+Alt+I / Cmd+Ctrl+I). Run /mcp.list — confirm optaeo appears with 6 (Enterprise) or 4 (Business) tools.

Step 3 · Verify the connection

Open a fresh chat in your AI client. Type:

List my OptAEO products with AEO score below 85.

Your assistant will request permission to call list_products with below_score: 85. Approve. You should get back your real OptAEO catalog with scores. If you are on Enterprise, try:

Run the OptAEO agent now.

You will see the run_agent tool fire and return a summary like "Agent run complete. Applied N fix(es) across M product(s)." If your store is already at Green tier, you might see "0 fixes applied" — that is correct. The plumbing is what matters here, not whether anything was eligible to fix.

Troubleshooting

Security notes

The MCP key in your config file is stored in plaintext on your machine. Anyone with file access to your home directory can read it. If your laptop is yours-only and full-disk-encrypted, this is fine — same threat model as your ~/.ssh/ keys. If shared, revoke the key after each use.

The MCP endpoint is HTTPS, so the key is encrypted in transit. We never log keys server-side; only their SHA-256 hash is stored. The last_used_at timestamp is updated on every call so you can spot a leaked key — if a revoked key shows recent activity, audit the machines that had it.

Keys are scoped to MCP operations only. They cannot read merchant settings, billing, or any data outside the MCP tool surface. They cannot be used for the regular OptAEO REST API.

Frequently asked questions