MCP API Reference

Overview

AEO Optima exposes a Model Context Protocol (MCP) server that allows AI assistants to access your brand visibility data, capture snapshots, run analytics, and more — all without leaving your AI tool.

Server URL: https://aeo-optima-mcp.onrender.com/mcp

Transport: Streamable HTTP (JSON-RPC over HTTP POST)

Authentication: Bearer token or OAuth 2.1

Getting Started

There are two ways to connect your AI client to AEO Optima:

Option A: Manual Token (Recommended — works everywhere)

1. Log in to the AEO Optima dashboard
2. Go to Settings > MCP / API
3. Click Generate New Token
4. Give it a name (e.g., "Claude Desktop") and select a role cap
5. Copy the token immediately — it's shown only once
6. Paste the token into your AI client's configuration (see Client Configuration below)

Option B: OAuth 2.1 (Click-to-connect)

Some AI clients (like Claude Desktop) support OAuth, which lets you connect with a single click — no token copying needed. When you click "Connect" in your AI client:

1. A browser window opens with the AEO Optima login page
2. You log in (or are already logged in)
3. A consent screen shows what the AI client is requesting
4. You pick your organization and approve
5. You're redirected back — connection is automatic

OAuth discovery endpoints:

• Authorization Server Metadata: https://aeo.techshu.ai/.well-known/oauth-authorization-server
• Protected Resource Metadata: https://aeo-optima-mcp.onrender.com/.well-known/oauth-protected-resource

OAuth supports PKCE (required), Dynamic Client Registration, refresh tokens, and token revocation.

Client Configuration

Replace aeo_YOUR_TOKEN with the token you generated from Settings > MCP / API.

Claude Desktop

Go to Settings > Connectors > Add Remote MCP Server and enter:

• Name: aeo-optima
• URL: https://aeo-optima-mcp.onrender.com/mcp
• Authorization Token: Your aeo_... token

Claude Desktop also supports OAuth — it will auto-discover the authorization server and guide you through the consent flow.

Claude Code (CLI)

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

Cursor

Create or edit .cursor/mcp.json in your project root:

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

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

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

OpenAI Codex (CLI, IDE extension, ChatGPT desktop)

One config covers the Codex CLI, the Codex IDE extension, and ChatGPT desktop — they share ~/.codex/config.toml.

OAuth (recommended — no token to store). AEO Optima's MCP server implements OAuth 2.1 with PKCE and open Dynamic Client Registration, which is exactly the flow codex mcp login drives:

[mcp_servers.aeo-optima]
url = "https://aeo-optima-mcp.onrender.com/mcp"
auth = "oauth"

Then run codex mcp login aeo-optima — your browser opens the AEO Optima consent screen and Codex stores the resulting credentials itself.

Static token fallback (headless machines / CI):

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

Then export AEO_OPTIMA_TOKEN=aeo_YOUR_TOKEN. You can also run the interactive codex mcp add aeo-optima and choose Streamable HTTP when prompted.

VS Code + Copilot

In VS Code 1.99+, go to Settings > MCP Servers and add:

• Type: http
• URL: https://aeo-optima-mcp.onrender.com/mcp
• Headers: Authorization: Bearer aeo_YOUR_TOKEN

ChatGPT / OpenAI

ChatGPT connects over OAuth — there is no token to paste. OpenAI's developer mode guide describes developer mode as "Available to Pro, Plus, Business, Enterprise, and Education accounts on the web", with SSE and streaming HTTP as the supported MCP protocols.

1. In ChatGPT, open Settings → Security and login and turn on Developer mode.
2. Following OpenAI's guide, create a developer-mode app for a remote MCP server with the server URL https://aeo-optima-mcp.onrender.com/mcp.
3. Choose OAuth as the authentication. AEO Optima supports Dynamic Client Registration, so no client ID or secret is needed.
4. Sign in on the AEO Optima consent screen, pick your organization and access level, and approve.

OpenAI states that ChatGPT respects readOnlyHint and that write actions require confirmation by default. For the OpenAI Agents SDK or your own code, use a Bearer token instead (see below).

Google Gemini

Google Gemini supports MCP at the SDK level. Add AEO Optima as a remote MCP server with the server URL and Bearer token.

Amazon Q Developer

In your CLI config or IDE plugin settings, add the MCP server URL with your Bearer token as a header.

OpenAI Agents SDK (Python)

from agents import MCPServerStreamableHttp
 
mcp = MCPServerStreamableHttp(
    url="https://aeo-optima-mcp.onrender.com/mcp",
    headers={"Authorization": "Bearer aeo_YOUR_TOKEN"}
)

Anthropic API (Direct)

Use the mcp_servers parameter in the Messages API:

{
  "mcp_servers": [{
    "type": "url",
    "url": "https://aeo-optima-mcp.onrender.com/mcp",
    "name": "aeo-optima",
    "authorization_token": "aeo_YOUR_TOKEN"
  }]
}

Authentication

AEO Optima supports two authentication methods. Both produce a Bearer token that is sent with every MCP request.

Method 1: Manual Tokens

Generated from the Settings page. Format: aeo_ + 48 random hex characters (52 characters total).

• SHA-256 hashed before storage — plaintext is never stored
• Optional expiration dates for time-limited access
• Can be revoked at any time from the Settings page
• Scoped to a specific user + organization

Method 2: OAuth 2.1

OAuth tokens are generated automatically through the browser-based consent flow. Format: oat_ + 48 random hex characters.

OAuth supports:

• Authorization Code + PKCE (S256 only) — no client secrets needed
• Dynamic Client Registration (RFC 7591) — AI clients auto-register
• Refresh Tokens — access tokens auto-renew without re-authorization
• Token Revocation (RFC 7009) — revoke access or refresh tokens
• Scopes: mcp:tools, mcp:resources, mcp:prompts

Role Hierarchy

Both token types have a role cap that limits what they can do, regardless of the user's actual role:

The effective permission is always the minimum of the token's role cap and the user's actual organization role.

Tools (120)

The MCP server exposes 120 tools — 113 customer-facing tools across 31 categories, plus 7 platform-owner-only tools that never appear for customer tokens. Tools that require a feature flag (Advanced Analytics, GEO Audit, GA4, GSC, Webhooks, Connectors, Citations, Crawlers, Content, Predictive, Enterprise, Query Universe, Fusion Insights) only work for organizations whose plan includes the corresponding feature.

Every tool advertises a short human-readable title (for example "Delete an alert rule") alongside readOnlyHint and destructiveHint. Clients that honour these hints can run read-only tools without asking and ask you to confirm anything that changes or deletes data.

Pagination & structured output

Every tool carries the MCP spec annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so clients can reason about a tool's safety before calling it. Large list tools are cursor-paginated and never silently truncate: get_snapshots, list_insights, and list_actions use a keyset cursor ordered on (created_at desc, id desc), while get_citations uses a documented offset cursor over its deterministically sorted source lists. Whenever more data exists, the response includes a nextCursor — pass it back as cursor to fetch the next page (an invalid cursor returns a clean 400 error):

{ "project_id": "...", "limit": 50, "cursor": "eyJjcmVhdGVkX2F0Ijoi..." }

Four tools — get_dashboard_metrics, get_citations, get_aeo_program, and get_criteria_map — also return structuredContent alongside the text block, with an outputSchema declared on the tool definition.

Projects (9)

Snapshots (3)

Analytics (4)

Advanced Analytics (5)

The first three tools require the ai_insights_advanced feature flag; list_emerging_competitors and get_share_of_model work on any plan with MCP access.

Sentiment counting (changed 4 September 2026): wherever a tool returns a sentimentBreakdown, its positive, neutral and negative counts are answers that named your brand AND carry a judged verdict — so a share computed over them is a share of answers that actually expressed something. Two residuals now travel beside them and are never folded in: notJudged (your brand was named, but no verdict was recorded) and notNamed (your brand was not in the answer, so no judgement was possible). Before this date an answer with no verdict was counted as neutral, which reported a missing judgement as a neutral opinion. The three key names and their types are unchanged, so existing integrations keep working; a neutral figure taken from before 4 September 2026 is not comparable with one taken after.

Segment filtering: All analytics tools — get_dashboard_metrics, get_analytics, get_sentiment_breakdown, get_entity_analysis, get_shopping_visibility, get_multi_language_analysis, get_visibility_forecast, detect_anomalies, analyze_citation_gaps, and generate_report — accept an optional segment parameter (all, branded, non-branded, or competitor) to filter by prompt type. All REST API analytics endpoints also accept ?segment= as a query parameter.

Prompts (9)

Page Analysis (1)

Models (1)

Alerts (6)

AI Analysis (2)

Criteria Map (2)

AEO Program (1)

Actions (2)

Plan & Quotas (1)

GEO Audit (3)

GA4 (3)

GSC (3)

Webhooks (2)

Citation Intelligence (4)

Crawler Intelligence (4)

Content Intelligence (6)

Connectors (2)

Predictive & Edge (3)

Enterprise (2)

Query Universe (9)

Agent-driven onboarding walkthrough: call analyze_company_site for a project, present the returned profile to the user for confirmation (items without an evidence quote are confidence low — treat them as suggestions to verify, never facts, and never write a certification the user has not explicitly confirmed), then apply the confirmed items with the write tools: manage_building_blocks (blocks), set_brand_facts (certifications as gate evidence), add_competitor, and update_project (category + industry business context). Finish with compose_prompts to generate query candidates from the confirmed universe.

Reports (10)

Schedules (3)

Goals (3)

Insights (2)

Intelligence (4)

Quick Audit (1)

Capture Runs (3)

expected_snapshot_count can be null on list_runs, get_run and diff_runs, since 2026-09-06. A run refused before it was sized — a paused organisation, or a credit gate, both of which stop the run before its fan-out is computed — has no expected count, and the field says so rather than reporting 0. Zero is a different statement: it means the run was sized and had nothing to capture.

A client that renders actual / expected should print something like "not sized" for the null case rather than a fraction. diff_runs carries expected_comparable: boolean — false when either run has no expected count, because there is no delta to take against an absence. The per-cell diffs count what was actually captured and are unaffected.

Admin — Platform Owner (7)

These tools are physically absent from the tool list for anyone who is not a platform owner — they never appear in tools/list for a normal customer token.

All platform-owner tools are only available to users whose email is listed in the PLATFORM_ADMIN_EMAILS environment variable.

Resources (11)

Resources are read-only data endpoints your AI assistant can browse for context. Three are static; the other eight are templated by ID.

Prompts (6)

Prompt templates generate structured reports from your data.

Rate Limits

Rate limits are enforced per token and tiered by your organization's plan:

The per-minute and per-hour caps cover all tools (resource reads and prompt fetches count too); the captures cap applies to capture_snapshot only. Unknown or missing plans fall back to the free-tier baseline — never a more permissive tier. The aeo://rate-limits resource advertises every tier's caps plus your org's effective limits, read from the same table the limiter enforces.

When rate limited, the tool returns an error with a retryAfterSeconds value.

Error Handling

Tool errors are returned as content with isError: true:

{
  "content": [{ "type": "text", "text": "{\"error\": \"...\", \"statusCode\": 401}" }],
  "isError": true
}

Audit Logging

Every tool call is logged for security and usage tracking:

• Who: Token, user, organization
• What: Tool name, input parameters (sanitized)
• When: Timestamp and duration
• Result: Success or error

Audit logs are viewable by organization admins.

Example Conversations

Check Mention Rate & Visibility Score

You: How is my brand doing on AI search engines today?

AI (calls list_projects then get_dashboard_metrics): Over the last 30 days your brand "TechShu" has a 30% mention rate and a Visibility Score of 49/100 across AI search engines, with a sentiment score of 72%. Average rank position is 3.2, up from 3.5 in the prior 30 days.

Capture a Snapshot

You: Run a snapshot for my "best CRM software" prompt

AI (calls list_prompts to find the prompt, then capture_snapshot): Captured responses from 8 AI models. Your brand was mentioned in 3 out of 8 responses. Sentiment was positive in 2 and neutral in 1.

Weekly Report

You: Generate my weekly visibility report

AI (invokes weekly_report prompt): Here's your weekly report for TechShu AEO Tracking...

OAuth 2.1 Developer Reference

If you're building an MCP client or integration that needs OAuth (rather than static tokens), here are the technical details.

Discovery

Your client should first fetch the Protected Resource Metadata to find the authorization server:

GET https://aeo-optima-mcp.onrender.com/.well-known/oauth-protected-resource

Then fetch the Authorization Server Metadata:

GET https://aeo.techshu.ai/.well-known/oauth-authorization-server

Dynamic Client Registration

Register your client automatically (RFC 7591):

POST https://aeo.techshu.ai/api/mcp/oauth/register
Content-Type: application/json

{
  "client_name": "My AI Tool",
  "redirect_uris": ["http://localhost:3000/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Redirect URIs must be either localhost (any port) or HTTPS.

Authorization Flow

1. Generate a PKCE code verifier (43-128 character random string) and its S256 challenge
2. Redirect the user to the authorization endpoint:

GET https://aeo.techshu.ai/api/mcp/oauth/authorize
  ?response_type=code
  &client_id=mcp_YOUR_CLIENT_ID
  &redirect_uri=http://localhost:3000/callback
  &code_challenge=BASE64URL_S256_HASH
  &code_challenge_method=S256
  &scope=mcp:tools mcp:resources mcp:prompts

3. User logs in, sees the consent screen, picks their organization and role cap, and approves
4. User is redirected to your redirect_uri with ?code=AUTH_CODE

Token Exchange

Exchange the authorization code for tokens:

POST https://aeo.techshu.ai/api/mcp/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&client_id=mcp_YOUR_CLIENT_ID
&redirect_uri=http://localhost:3000/callback
&code_verifier=YOUR_ORIGINAL_VERIFIER

Response:

{
  "access_token": "oat_...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "ort_...",
  "scope": "mcp:tools mcp:resources mcp:prompts"
}

Refresh Tokens

When the access token expires, use the refresh token to get a new one:

POST https://aeo.techshu.ai/api/mcp/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=ort_YOUR_REFRESH_TOKEN
&client_id=mcp_YOUR_CLIENT_ID

Token Revocation

Revoke an access token or refresh token (RFC 7009):

POST https://aeo.techshu.ai/api/mcp/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=oat_OR_ort_TOKEN

Always returns HTTP 200, regardless of whether the token was valid.

OAuth Scopes

All three scopes are granted by default if no scope is specified.

Compatibility