Connect AI Assistants to AEO Optima

What connecting gives you

AEO Optima runs a Model Context Protocol (MCP) server. An assistant connected to it can read your visibility data, capture snapshots, run analyses and generate reports, inside the organization and access level you choose.

Once connected, you can ask things like:

• "How is my brand visibility trending this month?"
• "Which competitors are gaining on us?"
• "Generate a PDF report for the leadership team"

The MCP API reference lists every tool, grouped by area, with the lowest role that can call it.

Before you connect

• Server URL: https://mcp.aeo.techshu.ai/mcp
• Transport: Streamable HTTP.
• Your plan. MCP access is included from the Pro Individual plan upward. On Free and Starter, every tool call is refused with a 403, although listing the tools can still succeed.

An assistant signs in one of two ways:

• OAuth. The assistant opens an AEO Optima sign-in page and you approve it. There is no token to copy. AEO Optima supports OAuth 2.1 with PKCE and dynamic client registration, so the assistant registers itself.
• A static token. You generate a token in AEO Optima and add it to the assistant's configuration.

Generate a token

1. In AEO Optima, go to Settings → MCP / API and click Generate Token.
2. Give the token a name and choose a Role cap. Choose the lowest one that does the job: Viewer is enough to read data.
3. Copy the aeo_… token. It is shown only once.
4. Send it on every request as the header Authorization: Bearer aeo_…. Include the word Bearer and the space; AEO Optima refuses a token sent without them.

Which way each assistant connects

The Verified badge on the consent screen

When an assistant signs in with OAuth, AEO Optima shows a consent screen before any access is granted. It shows a green Verified badge only when both of these are true of the application as it registered with AEO Optima (not of the link that opened the page):

• its name reads as one of the vendors below, and
• every return address it registered is on that vendor's hosts (a subdomain of a listed host counts).

AEO Optima compares names by what they look like, not by their exact letters. Common lookalike letters from other alphabets (such as a Cyrillic С in place of a Latin C), full-width and other styled letters, and accented letters read as the plain letter (letters with a stroke, such as ł or ø, and ligatures such as æ or ß are ignored instead), and invisible characters are ignored; the letters i and l and the characters 1 and | read alike, as do 0 and o, and “rn” is read both as it is written and as “m”. Inside a word that contains a plain Latin letter, everything other than the letters a to z and the digits 0 to 9 is ignored: punctuation such as hyphens, dots and underscores, and characters from other alphabets that look like punctuation (“Cla-ude”, “c.l.a.u.d.e”, “Cla٠ude”). A letter from another alphabet that looks like a Latin letter but is not one of the common lookalikes above (such as ǀ in place of l) is ignored rather than read as that letter, so a brand name spelled with one is not caught. A name written entirely in another alphabet's lookalike letters (such as Lisu ꓚꓡꓮꓴꓓꓰ) is not caught either. Letters typed one at a time with spaces between them are joined (“C l a u d e”). A brand counts anywhere inside a single word, so “ClaudeAI” reads as Claude. Spaces between whole words are kept: a brand name of seven or more letters (such as ChatGPT or Microsoft) still counts when a space splits it (“Chat GPT”), but a shorter one (such as Meta, AWS or OpenAI) counts only inside one word, so “Home Tab” or “Kafka WS” is not read as a brand, and neither is “Open AI”. A name that contains characters which change the direction text is displayed in is refused. A name that contains any space other than an ordinary space is refused. A name that reads as any well-known brand, but whose return addresses are not that brand's verified hosts, gets a yellow warning instead of the badge, and a new registration like that is refused. A consent link that names an application or a return address that is not registered shows no consent form at all.

Claude.ai (web, desktop and mobile)

Claude.ai connects over OAuth through a custom connector. There is no token to paste.

1. Open Claude's connector settings:

   • Free, Pro and Max plans: go to Customize > Connectors and click Add custom connector.
   • Team and Enterprise plans: an owner goes to Organization settings > Connectors, selects Add, then Custom (if Claude asks for the connector type, choose Web). Members then go to Customize > Connectors, find the connector with the "Custom" label, and click Connect.

2. Paste the server URL https://mcp.aeo.techshu.ai/mcp, click Add, then click Connect.

   If the Add custom connector dialog has two steps, choose Sign in now under Authentication and Register automatically under OAuth client. AEO Optima supports dynamic client registration and needs no client ID of your own, so don't choose Use your own OAuth client.

3. An AEO Optima authorization page opens. Sign in with your usual account (Google, or email and password).

4. Check the consent screen. It shows the Client ID and Redirect host of the application asking for access. For Claude.ai the redirect host is claude.ai, with a green Verified Anthropic (Claude) application badge (see the Verified badge). If an application calls itself Claude but shows no badge, do not approve it.

5. Choose your Organization and Access level (Viewer (read-only), Member (read + write) or Admin (full access), capped at your own role), then click Authorize.

6. Claude.ai shows AEO Optima as connected. To turn it on or off for a conversation, use the + button in the chat and open Connectors.

To check it works, ask Claude: "List my AEO Optima projects."

"Couldn't register with AEO Optima's sign-in service." Leave the OAuth Client ID field empty (in the two-step dialog, keep Register automatically). If trying again doesn't help, contact AEO Optima support: the fix is on our side.

"Your connection to AEO Optima stopped working. Reconnect to continue." This is normal after a session expires or is revoked. Click Reconnect.

A fixed token instead of signing in (beta)

Claude's documentation says: "Request header authentication is in beta and available to a limited set of organizations." If your organization has it, choose No sign-in under Authentication in the Add custom connector dialog, open Request headers, choose authorization, and enter Bearer aeo_… as the value.

• Everyone in your Claude organization who uses that connector acts as the AEO Optima user who generated the token. If each person should act as themselves, use the sign-in flow above.
• Claude does not let you change authentication settings after a connector is added. To change the token, remove the connector and add it again.

Claude Code

Claude Code connects with a static token; signing Claude Code in with OAuth is not supported yet.

claude mcp add --transport http aeo-optima https://mcp.aeo.techshu.ai/mcp \
  --header "Authorization: Bearer aeo_YOUR_TOKEN"

This follows the command syntax in Claude Code's MCP documentation.

ChatGPT

ChatGPT connects over OAuth in developer mode. There is no token to copy or paste.

OpenAI's developer-mode guide says developer mode is "Available to Pro, Plus, Business, Enterprise, and Education accounts on the web". It also says developer mode provides "full Model Context Protocol (MCP) client support for all tools, both read and write. It's powerful but dangerous."

1. In ChatGPT, open Settings → Security and login and turn on Developer mode.
2. Following OpenAI's guide, go to ChatGPT Plugins, select the plus button, and create a developer-mode app for a remote MCP server with the URL https://mcp.aeo.techshu.ai/mcp.
3. Choose OAuth as the authentication. AEO Optima supports dynamic client registration, so ChatGPT needs no client ID or secret from us.
4. ChatGPT opens the AEO Optima authorization page. Sign in with your usual account.
5. Check the consent screen. The redirect host should be on chatgpt.com or openai.com, with a green Verified OpenAI (ChatGPT) application badge. AEO Optima refuses any registration that names ChatGPT or OpenAI but sends the sign-in anywhere else. If an application calls itself ChatGPT but shows no badge, do not approve it.
6. Choose your organization and access level, then click Authorize.

See OpenAI's developer mode guide.

Grok

xAI documents two ways to use your own MCP server: a custom connector in the Grok app, and the remote MCP tool in the xAI API.

A custom connector in the Grok app

xAI's connectors guide says: "If you need to connect Grok to a service not available in the catalog, you can bring your own Model Context Protocol (MCP) server."

• Individual accounts: go to grok.com/connectors, click New Connector, select Custom, enter the server URL and complete any required authentication.
• Grok Business and Enterprise: xAI says "a team admin must first provision a connector in the cloud console before it is available to members of the organization."

xAI does not document whether a custom connector completes an OAuth sign-in or accepts a fixed token. When a client connects without a credential, AEO Optima answers 401 Unauthorized with a WWW-Authenticate header that points at its OAuth metadata, which is the standard MCP signal to start a sign-in. If Grok follows it, you will see the AEO Optima consent screen; check that the redirect host belongs to xAI or Grok before you approve. If no AEO Optima sign-in page appears, use the xAI API instead.

The xAI API remote MCP tool

xAI's remote MCP guide says: "Only Streaming HTTP and SSE transports are supported." AEO Optima's server uses Streamable HTTP. Pass your token in the authorization field and include the Bearer prefix: AEO Optima requires it, and xAI does not say it adds one.

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
  "model": "YOUR_GROK_MODEL",
  "input": [
    { "role": "user", "content": "List my AEO Optima projects." }
  ],
  "tools": [
    {
      "type": "mcp",
      "server_url": "https://mcp.aeo.techshu.ai/mcp",
      "server_label": "aeo-optima",
      "authorization": "Bearer aeo_YOUR_TOKEN",
      "allowed_tools": ["list_projects", "get_project", "get_dashboard_metrics"]
    }
  ]
}'

xAI's guide notes that "The require_approval and connector_id parameters in the OpenAI Responses API are not currently supported", so nothing asks you before Grok calls a tool this way. List only the tools you want in allowed_tools, and use a token with the Viewer role cap unless Grok should change data.

OpenAI Codex

Codex reads MCP servers from ~/.codex/config.toml. Give it your token through an environment variable:

[mcp_servers.aeo-optima]
url = "https://mcp.aeo.techshu.ai/mcp"
bearer_token_env_var = "AEO_OPTIMA_TOKEN"

Then set AEO_OPTIMA_TOKEN to your aeo_… token.

OpenAI's Codex MCP guide says codex mcp login signs in through a callback on your own computer (http://127.0.0.1/callback by default). AEO Optima's sign-in service does not accept a callback to a local address, so use the token.

Cursor

Cursor reads .cursor/mcp.json in your project, or ~/.cursor/mcp.json in your home directory for every project:

{
  "mcpServers": {
    "aeo-optima": {
      "url": "https://mcp.aeo.techshu.ai/mcp",
      "headers": {
        "Authorization": "Bearer aeo_YOUR_TOKEN"
      }
    }
  }
}

See Cursor's MCP documentation.

VS Code with GitHub Copilot

VS Code reads .vscode/mcp.json in your workspace. An http server accepts headers, which VS Code describes as "HTTP headers for authentication or configuration":

{
  "servers": {
    "aeo-optima": {
      "type": "http",
      "url": "https://mcp.aeo.techshu.ai/mcp",
      "headers": {
        "Authorization": "Bearer aeo_YOUR_TOKEN"
      }
    }
  }
}

VS Code's MCP servers guide recommends: "Avoid hardcoding sensitive information like API keys. Use input variables or environment files instead." The headers field is described in VS Code's MCP configuration reference.

Windsurf

Windsurf reads ~/.codeium/windsurf/mcp_config.json. A remote server takes serverUrl and headers:

{
  "mcpServers": {
    "aeo-optima": {
      "serverUrl": "https://mcp.aeo.techshu.ai/mcp",
      "headers": {
        "Authorization": "Bearer aeo_YOUR_TOKEN"
      }
    }
  }
}

See Windsurf's MCP documentation.

Gemini CLI

Gemini CLI reads MCP servers from mcpServers in its settings.json. A Streamable HTTP server takes httpUrl, with headers for the token:

{
  "mcpServers": {
    "aeo-optima": {
      "httpUrl": "https://mcp.aeo.techshu.ai/mcp",
      "headers": {
        "Authorization": "Bearer aeo_YOUR_TOKEN"
      }
    }
  }
}

See Gemini CLI's MCP server documentation.

Amazon Q Developer

Amazon Q Developer's MCP guide says its CLI "supports both local MCP servers (that run as processes) and remote MCP servers (that communicate over HTTP). Remote servers can use OAuth authentication or be open with no authentication required."

See Using MCP with Amazon Q Developer for how Amazon Q configures remote servers.

OpenAI Agents SDK

Based on the example in the Agents SDK MCP guide:

from agents.mcp import MCPServerStreamableHttp
 
async with MCPServerStreamableHttp(
    name="AEO Optima",
    params={
        "url": "https://mcp.aeo.techshu.ai/mcp",
        "headers": {"Authorization": "Bearer aeo_YOUR_TOKEN"},
    },
) as server:
    ...  # pass `server` in your agent's mcp_servers list

Anthropic API

Anthropic's MCP connector lets the Messages API call a remote MCP server directly. It is in beta and needs the header anthropic-beta: mcp-client-2025-11-20. Anthropic's documentation says the server must be reachable over HTTP ("supports both Streamable HTTP and SSE transports") and that "only tool calls are currently supported."

curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "YOUR_CLAUDE_MODEL",
    "max_tokens": 1000,
    "messages": [{"role": "user", "content": "List my AEO Optima projects."}],
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://mcp.aeo.techshu.ai/mcp",
        "name": "aeo-optima",
        "authorization_token": "aeo_YOUR_TOKEN"
      }
    ],
    "tools": [
      { "type": "mcp_toolset", "mcp_server_name": "aeo-optima" }
    ]
  }'

Anthropic's own example passes the token alone in authorization_token, without the word Bearer. See Anthropic's MCP connector documentation.

What an assistant asks before running a tool

Every AEO Optima tool carries a short human-readable title (for example "Delete an alert rule") and the MCP hints readOnlyHint and destructiveHint.

• Claude. Claude's connector documentation says these hints "determine auto-permissions in Claude: read-only tools can run without per-call confirmation; destructive tools always prompt."
• ChatGPT. OpenAI's guide says: "We respect the readOnlyHint tool annotation. Tools without this hint are treated as write actions." It also says: "Write actions by default require confirmation."
• Grok. xAI does not document how Grok uses tool hints.

Before you approve a write, check what the assistant is about to send, especially project IDs and anything that deletes.

Access levels

• The access level you grant during sign-in, or a token's role cap, can never exceed your own role in the organization.
• With Viewer access, AEO Optima refuses every tool that changes something.
• A project in strict isolation mode is visible only if you are an explicit member of it.

Revoking access

Revoking the session under Settings → MCP / API ends it: the assistant's next call is refused and it must sign in again. A revoked static token is refused on its next call too.

Removing the connector inside Claude, ChatGPT or Grok stops that assistant from using it. To end the session on AEO Optima's side as well, revoke it under Settings → MCP / API.

Rate limits

Rate limits apply per token and depend on your organization's plan: from 60 requests a minute, 500 an hour and 5 captures an hour on Pro Individual, up to 600 requests a minute, 50,000 an hour and 500 captures an hour on Custom. Quick brand checks have their own hourly cap, the same size as the captures cap, so they never use up your captures. When a limit is reached, the error carries a retryAfterSeconds value. See the MCP API reference for every tier.

Security

• Tokens are stored only as a hash, never in plain text.
• Every OAuth sign-in requires PKCE with the S256 method.
• Each token refresh issues a new refresh token and retires the old one. If a retired refresh token is presented again, the whole session is revoked.
• Every authenticated tool call is logged with the tool name, project, sanitized inputs and outcome.
• You can review your own assistant connections and recent tool calls on the AI agents page. Owners and admins find it under Settings in the sidebar.

Related

• MCP API reference — every tool, with its parameters and minimum role
• Webhooks — real-time events for automation
• Plans — feature availability by plan tier