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://mcp.aeo.techshu.ai/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. The step-by-step setup for each assistant is on one page, Connect AI assistants; this page is the reference.

Option A: Manual Token

1. Log in to the AEO Optima dashboard
2. Go to Settings > MCP / API
3. Click Generate Token
4. Give it a name (e.g., "Claude Code") 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 (Claude.ai and ChatGPT) sign in with OAuth, so there is no token to copy. When you connect from 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 access level, 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://mcp.aeo.techshu.ai/.well-known/oauth-protected-resource

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

Client Configuration

The setup for each assistant is on Connect AI assistants. If the assistant uses a token, start with Generate a token; Which way each assistant connects summarises every assistant.

• Claude.ai (web, desktop and mobile) — OAuth; a fixed token instead of signing in is in beta
• Claude Code — token
• ChatGPT — OAuth, in developer mode
• Grok — a custom connector in the Grok app, or the xAI API remote MCP tool with a token
• OpenAI Codex — token
• Cursor — token
• VS Code with GitHub Copilot — token
• Windsurf — token
• Gemini CLI — token
• Amazon Q Developer — see Amazon Q Developer's MCP guide
• OpenAI Agents SDK — token
• Anthropic API — 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

The MCP server exposes the customer-facing tools below, grouped by category, plus 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..." }

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

Snapshots

Analytics

Advanced Analytics

get_entity_analysis, get_shopping_visibility and get_multi_language_analysis 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.

Tone is counted from judge-scored answers only (changed 17 September 2026): when the sentiment judge cannot be reached, a word list still records a verdict so the capture is not lost. A word list is a stand-in for a reading, not a reading, and until this date every tool counted the two as one thing — while the product's own Sentiment page had stopped counting them on 16 September, a day earlier. From 17 September the verdict counts on get_analytics (overallStats.sentimentBreakdown and each entry of promptPerformance) and on get_sentiment_breakdown (overall, byPrompt, byModel) cover judge-scored answers only, and each payload states the population it is over in an additive tonePopulation field, whose one value today is judge_scored. Measured over the 30 days to 16 September 2026, this moved 1,875 counted answers to 1,777 across nine projects — but read the per-project figures in the analytics guide before the average: eight of the nine move by 8% or less while one loses close to a third. Three things to know: total on get_sentiment_breakdown is now the sum of the three verdict counts (the judge-scored answers), with named carrying the figure it used to hold and notJudged carrying the difference, so a share computed from this payload divides by the population its numerators came from; get_snapshots returns sentimentMethod (judge | word_list | no_record) on every row and its sentiment filter now matches judge-scored rows only, so it returns fewer rows than before for the same value; and get_dashboard_metrics is deliberately unchanged — its sentimentScore, sentimentPolarity and positiveRate still cover every brand-mentioning answer, exactly as their field descriptions say. get_entity_analysis did not move either: its per-entity tone has always read judge-written rows only.

Which tools moved. get_analytics, get_sentiment_breakdown, get_shopping_visibility and get_multi_language_analysis all count fewer answers than they did before 17 September 2026, and each now states tonePopulation in its response. get_snapshots and capture_snapshot do not count anything, but every row they return carries sentimentMethod, and get_snapshots' sentiment filter narrowed. get_shopping_visibility also gains notJudgedReasons: its per-row sentiment: 'not_judged' token now covers four different facts — the answer named nobody, a word list wrote the verdict, nothing records how it was scored, or a judge scored it and stored no usable verdict — and those four counts sum to exactly the number of not_judged rows. An existing field's VALUE moved there, not just its shape: a row the split no longer counts now reads sentiment: "not_judged" where it previously reported the stored verdict — because a word list wrote that verdict, because nothing records how it was scored, or because the answer named nobody. Measured live on 17 September 2026, 154 of the 161 rows that move are the middle case, so most of the drop is missing provenance rather than a word list. Read notJudgedReasons for the split. The shape is additive; the values are not. get_multi_language_analysis gains judgedAvgSentiment, which is null where the deprecated avgSentiment reads 0, and whose non-zero value also moved, because the mean's population narrowed with the counts; on a −1…1 scale 0 means "perfectly balanced", so a language whose every answer a word list scored used to report a balanced tone it never measured.

What moves an answer out of the count. Two things, and only the first is what the measured figures above are made of: a verdict a word list wrote, and a row that does not record how it was scored at all. Over the 30 days those figures cover, all 98 dropped answers were word-list verdicts and none were missing-provenance rows — so the explanation above is complete for that window. It is not complete platform-wide: rows carrying no provenance key exist in older data and they stop counting too, for the same reason (silence is not a record that a judge did the reading).

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

Page Analysis

Models

Alerts

AI Analysis

Criteria Map

AEO Program

Scorecard

Actions

Plan & Quotas

GEO Audit

GA4

GSC

Webhooks

Citation Intelligence

Crawler Intelligence

Content Intelligence

Connectors

Predictive & Edge

Enterprise

Query Universe

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: create_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

Schedules

Goals

Insights

Intelligence

Quick Audit

A quick audit does not score tone (changed 17 September 2026): this tool reports whether each engine names the brand. It never ran the sentiment judge — but until this date it returned a tone regardless: sentiment carried the hardcoded string "neutral" on every answer that named the brand, identical for every brand and every answer, and the public web version of the same check scored a private seventeen-word list. An existing field's VALUE moved here, not its shape: sentiment is unchanged as a field and is now always null, with an additive sentimentBasis of not_scored on each model entry and a plain-language sentimentBasisNote on the payload. A caller that read sentiment as a verdict was reading a constant, not a measurement; for real tone use get_sentiment_breakdown or get_analytics, which are judge-scored over your tracked questions.

A quick audit reports over the engines that ANSWERED (changed 17 September 2026): visibility now carries answered and errored beside the existing mentioned and total, and the percentage is computed over answered rather than over the engines the audit tried. percentage is an existing field whose VALUE moved: it is null — never 0 — when no engine answered, with reason: "engines_unreachable" and a plain sentence in note. Before this, three refused calls were published as { mentioned: 0, total: 3, percentage: 0 } and cached for 24 hours, so a caller was told no engine mentions the brand when in fact none had been reached. A caller that branches on percentage must handle null and must not coerce it to 0: the two mean different things. total still means the engines we tried, and there is deliberately no asked field repeating it. A run in which nothing answered is not cached, so the next call retries rather than being handed the same refusal.

Caching: results are cached for 24 hours per brand. Before 17 September 2026 this tool's cache write violated a NOT NULL constraint and failed silently, so no result was ever reusable and every call ran three models afresh. The cached payload is now also checked against the surface that produced it, so this tool is never served a row written by the public web check, whose prompt and payload differ.

A quick audit reports NAMING, not knowing (changed 24 September 2026): an engine counts in mentioned when its answer contains the brand name, and an answer that says "I don't have reliable information about Zorvane" contains it — so a made-up brand can be named by every engine. The count is unchanged; what changed is that the payload now says what it is. percentage keeps its value: it is the named rate (mentioned ÷ answered, null when nothing answered). The payload carries an additive top-level namingNote, the same sentence every screen prints. Each model's excerpt is now the engine's opening lines — about 300 characters from the start of its answer, cut at a word boundary, with markdown emphasis and link syntax removed — for every engine that answered, named or not, and null only for an engine that did not answer. It used to be the first 200 characters untrimmed here and a window around the name on the web check, so an opening "I don't have reliable information about…" could be cut away. A call refused before any engine runs — the platform paused, the platform balance below its floor, a check that could not be completed, or an engine lineup that could cost more than a quick audit is allowed to — fails with one message, Quick audit is temporarily unavailable. Please try again later., whichever it was; it used to carry the refusing gate's internal detail. From the same date brand_name is cleaned the way the web check cleans it (control, format, bidi and zero-width characters removed, whitespace collapsed), the cleaned name is the one asked about, cached and returned, and it must be 2–80 characters before cleaning: the web check cuts a longer name to 80 characters after cleaning, this tool refuses it with an invalid-arguments error. A name that, once cleaned, has fewer than 2 characters or no letter or digit is refused on both. Each call, a cached answer included, also counts toward its own hourly cap, the same size as the plan's captures-per-hour cap and separate from capture_snapshot's. Results cached before this date, or under an earlier wording of namingNote, are recomputed on the next call rather than served.

A cut-off answer is neither named nor not named (changed 25 September 2026): each model entry carries an additive cutOff: true when the engine ran out of output budget before it finished — the gateway's finish_reason: "length", or the provider's native MAX_TOKENS, read from the response and never inferred from the text. Such an entry has mentioned: false and sits outside both sides of the count. visibility carries an additive cutOff count: percentage is mentioned over answered − cutOff, and it is null — with reason: "answers_cut_off" and a plain sentence in note — when every engine that answered was cut off, a different condition from engines_unreachable. The output budget per engine now follows the model: an engine the model registry describes as reasoning, or has not yet described, is asked with 1,500 output tokens where it was a flat 200 here and 500 on the web check (gemini-3.6-flash spent 479 of 500 on reasoning and returned 65 characters of junk), and the lineup is priced at each engine's own budget before any call. A result in which any engine was cut off is not cached, so the next call runs the engines again.

Capture Runs

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.

A run cut short says why, per cause (added 25 September 2026): a run that captured fewer answers than it planned carries an additive metadata.shortfall on list_runs and get_run — one entry per cause, each { count, reason }, with count null when the run was refused before it was sized. The causes are model_not_served (an engine whose model the registry no longer serves, skipped before any call, never charged, not counted against the allowance or the daily cap), provider_declined (the AI provider could not take the answers; nothing was charged), platform_capacity and platform_pause (a platform-side pause), plan_cap (the daily cap, the included allowance or the pay-as-you-go cap) and provider_error. Two more from 23 October 2026, both on a scheduled run that never started, with count null: start_failed (the platform could not start it; it is retried every hour and the cycle is kept) and empty_group (the schedule's question group has no active questions). reason is the same plain sentence the Cycles pages print; nothing internal is in it. skipped_snapshot_count is the model_not_served count on a run that ran; a run refused before it ran keeps the whole planned count there. Runs recorded before that date carry no shortfall. Nothing was renamed or removed.

Admin — Platform Owner

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

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

Prompts

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, and quick_audit has its own hourly cap of the same size (from 24 September 2026 — before that quick_audit counted only toward the per-minute and per-hour caps). 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
}

When a tool fails because the data it reads could not be loaded, the error reads "We couldn't load this data just now. Try again in a few minutes." — never the database's own message. The same holds for a per-row error inside a successful result (set_brand_facts).

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://mcp.aeo.techshu.ai/.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": ["https://your-app.example.com/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Redirect URIs must use HTTPS. In production, localhost and 127.0.0.1 redirect URIs are refused, as are private or internal hosts, URIs that carry a user name or password, and URIs with a fragment.

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=https://your-app.example.com/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=https://your-app.example.com/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