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-optima.vercel.app/.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"
      }
    }
  }
}

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

In Developer Mode, go to MCP Servers and add the server URL with your Bearer token.

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 (65)

The MCP server exposes 74 tools across 29 categories. Tools that require a feature flag (Advanced Analytics, GEO Audit, GA4, GSC, Webhooks, Connectors, Citations, Crawlers, Content, Predictive, Enterprise, Query Universe) only work for organizations whose plan includes the corresponding feature.

Projects (2)

Snapshots (3)

Analytics (4)

Advanced Analytics (3) — ai_insights_advanced feature flag

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 (3)

Page Analysis (1)

Models (1)

Alerts (1)

AI Analysis (2)

Actions (2)

Plan & Quotas (1)

GEO Audit (2)

GA4 (2)

GSC (2)

Webhooks (2)

Citation Intelligence (3)

Crawler Intelligence (2)

Content Intelligence (3)

Connectors (2)

Predictive & Edge (3)

Enterprise (2)

Query Universe (6)

Reports (6)

Goals (3)

Insights (2)

Intelligence (3)

Quick Audit (1)

Admin — Customer (2)

Admin — Platform (5)

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

Resources (10)

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

Prompts (6)

Prompt templates generate structured reports from your data.

Rate Limits

When rate limited, the tool returns an error with a retryAfter value in seconds.

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): Your brand "TechShu" has a 30% mention rate and a Visibility Score of 49/100 across AI search engines today, with a sentiment score of 72%. Average rank position is 3.2, up from 3.5 last week.

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-optima.vercel.app/.well-known/oauth-authorization-server

Dynamic Client Registration

Register your client automatically (RFC 7591):

POST https://aeo-optima.vercel.app/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-optima.vercel.app/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-optima.vercel.app/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-optima.vercel.app/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-optima.vercel.app/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