Getting started with the aeomcp MCP server

Connect to the host you were given — production and staging are separate deployments on separate domains, and this page ships inside the server image, so it is the same text in both. The path is always /mcp (Streamable HTTP) on whichever host you are pointed at:

claude mcp add aeomcp --transport http https://<your-aeomcp-host>/mcp

If you are unsure which host that is, the server tells you: fetch /.well-known/oauth-protected-resource on it and read the resource field. That document is public and needs no credential — it is the same value this deployment validates tokens against, so it is authoritative in a way a documentation page cannot be.

Authenticating

The credential most people use is a personal access token (apt_…), created in the studio at /o/<org>/connect ("Connect MCP"): pick your assistant and up to five client workspaces, and the page shows the exact claude mcp add … --header "Authorization: Bearer apt_…" command or config block for it, once. What it can change depends on your role (see authentication.md). Send it as Authorization: Bearer apt_…. An API key (awk_…, Settings → API keys, explicit scopes) is the credential for agents, CI and servers.

Interactive OAuth sign-in is supported by the server but is not enabled on every deployment. Check before relying on it: if /.well-known/oauth-protected-resource lists an authorization_servers member, OAuth is available and your MCP host will discover the flow from there. If that member is absent, this deployment is API-key-only — an absent member is a deliberate "not advertised here" rather than an oversight (see authentication.md).

First calls

Start with get_account_context: it returns your organization, role, permitted workspaces, plan, scopes and feature flags.

The tools you see are exactly the tools your role, plan and scopes allow — nothing is advertised that you cannot call, so tools/list is itself an answer about your permissions. describe_capabilities shows the full picture: every tool this server knows about, which ones your token can call right now, and the tier and scope each one needs.

Every analytical tool takes the same window argument (start_date, end_date, engines, filters) and returns the same columnar envelope: columns, rows, row_count, and a trace_id you can quote to support. window.location_id narrows to one market location (ids come from list_market_locations); omit it for every answer, with a location-tracked prompt's cities averaged so the prompt counts once.

Every tool also accepts an optional context (one sentence on your goal; logged, never required) and, on list and report tools, fields (the subset of columns you want back, in the tool's order). See reports, templates and peec-to-aeomcp.

list_prompts, get_prompt, export_prompts, list_prompt_candidates, get_answer and get_answers_report carry three more columns — monthly_volume, volume_keyword, volume_as_of: the Google search demand of the keyword linked to each prompt. This is how often people search Google for that keyword, not how often AI engines are asked the prompt, and it is null (never 0) when nothing is linked or measured.

get_prompt also returns geo_local and by_location — for a location-tracked prompt, each location's answered chats and own-brand visibility over the window (empty for any other prompt).

Creating and updating brands, prompts, topics, tags and classifications goes through a separate, bulk-only contract — dry_run to preview, idempotency_key to retry safely — covered in writes. The same page covers configuring a workspace (its collection schedule, daily watchlist, brand profile and topics) and starting a collection round on demand, both of which agents can do directly.

Tools also exist for run/collection status, plan capacity and usage, agency portfolio views (across the workspaces a plan grants), and member and MCP-connection reads — see tools.md for the full catalog. get_run's warnings column groups a run's warnings as {code, engine, count, sample} (e.g. geo_units_summary: how many location runs could not be verified), and get_plan_and_usage carries local_tracking_contexts / daily_local_tracking_contexts rows — the 10% local-tracking allowance and its use.

Engines

window.engines names public engine names: chatgpt, google_ai_mode (Google AI Mode), google_ai_overview (Google AI Overview — opt-in per workspace, collects only where Google shows an overview; queries with none come back answered: false), gemini. google_ai is also accepted and means both Google engines (google_ai_mode and google_ai_overview) together.

Every envelope's provenance.engine_ids maps each public engine name in your query to the internal id(s) it resolved to (support/trace_id lookups use these). Most names resolve to one id (a plain string); google_ai resolves to an array of both — provenance.engine_ids.google_ai is now ["google-0", "google-aio-0"] (previously a single id string). If your client assumed a single string for every key, handle the array case for google_ai specifically.

The Google AI Mode relabel (what used to be google_ai_overview is now google_ai_mode) and the new AI Overview channel are described in release-notes-google-ai-overview — read it if your client stores engine names or parses provenance.engine_ids.