Need public brand information? Keyless Optimly Index reads require no credentials.

Developer reference · MCP

Optimly MCP connector

One endpoint, 16 tools, and the brand named per call — by a credential that reaches every brand in your organization, or one pinned to a single brand. The connector speaks Streamable HTTP and keeps no session, so any request can land on any instance.

This connector exposes your organization's BrandVault, not the public Optimly Index. There is no public-index MCP server yet; use the keyless HTTP quickstart for public brand data.

Endpoint

Server URLhttps://app.optimly.ai/api/mcp
TransportStreamable HTTP, JSON responses, stateless
AuthenticationAuthorization: Bearer — an organization sk_live_… key, a brand-scoped one, or an oat_ OAuth access token
Rate limit60 requests per minute per token, shared with the keyed REST API
BrandNamed per tool call with the brand argument — an id, a slug or the unique name — and defaulted when the organization has one brand. A brand-scoped key or connection pins it instead, and refuses a sibling.

Connect a client

Create a key in the application under Connections — it is shown once, and leaving its scope on every brand gives you one credential for all of them. The shapes below cover the clients most people use; the Connections page has the paste-ready setup, extraction, and interview prompts that go with them.

Claude Code

Add the HTTP server with the current CLI syntax, then keep the key in an environment variable:

claude mcp add --transport http optimly https://app.optimly.ai/api/mcp \
  --header 'Authorization: Bearer ${OPTIMLY_KEY}'

The single quotes matter: Claude Code stores the ${OPTIMLY_KEY} reference and expands it from the environment when it connects, so the raw key is never written to the client configuration. The variable must be set in the environment that launches the client. If you prefer OAuth instead of a static key, omit the header and run claude mcp login optimly, then complete the consent screen in the browser.

Cursor and other JSON clients

Clients that accept HTTP servers in an mcpServers map use a url and a headers object:

{
  "mcpServers": {
    "optimly": {
      "url": "https://app.optimly.ai/api/mcp",
      "headers": { "Authorization": "Bearer <your-key>" }
    }
  }
}

This shape is not the Claude Desktop config file format. Claude Desktop connects through Settings → Connectors → Add custom connector, where the connector URL is https://app.optimly.ai/api/mcp and the authentication is OAuth.

Hosted connectors

Add a custom connector pointing at https://app.optimly.ai/api/mcp and complete the OAuth consent screen in the browser. The connector discovers the flow on its own: an unauthenticated request answers 401 with a WWW-Authenticate header naming the resource metadata at https://app.optimly.ai/.well-known/oauth-protected-resource, which in turn advertises the authorization server at https://app.optimly.ai/.well-known/oauth-authorization-server. PKCE with S256 is required.

On Claude Team/Enterprise and ChatGPT workspaces, an admin adds the connector once and each member then connects. The server URL is https://app.optimly.ai/api/mcp.

Verify the connection

A server that answers is not the same as a credential that resolved your organization and brand. Check both layers:

  1. Run claude mcp list (or your client's equivalent). The optimly entry should show https://app.optimly.ai/api/mcp as an HTTP server and report a successful connection.
  2. Call list_brands to see what the credential reaches.
  3. Call get_brand for the brand you mean, and check the name and canonical_domain it returns.

Do not treat the connection as working until get_brand succeeds. An unauthenticated sanity check is also useful: curl -i https://app.optimly.ai/api/mcp must answer 401 with a WWW-Authenticate header pointing at the resource metadata — that proves the endpoint is reachable and speaking the discovery protocol.

Tool reference

All 16 tools, as the connector advertises them. Reading is unconstrained; the writable surfaces are publish_vault, act_on_recommendation, and create_brand. No tool starts a measurement run.

list_brands

The brands this credential can reach — the list every other tool's `brand` argument is drawn from, with each brand's id, name, domain and slug. A brand-bound credential sees only its own; an org-wide one sees the whole organization. Listed first on purpose: a caller that does not know what it can reach should be able to find out before it tries to read or write anything.

No parameters beyond the authenticated brand.

get_brand

Identity of the authenticated brand: name, canonical domain, slugs, claim state.

ParameterTypeRequiredDescription
brand any no

create_brand

Create a brand in the authenticated organization. Only an **org-wide** credential whose owner is a **trusted user** may call this; a brand-bound credential already pins one brand and cannot create another. Because this writes, confirm the brand name and website with the user before calling it. An exact canonical-URL match already in the organization returns that brand with `created: false` and does not start a second prefill. On a new brand the site prefill scrape is queued; the interactive interview and any report run are deliberately not started.

ParameterTypeRequiredDescription
name string yes
website_url string yes

get_vault

The brand's active vault: all sections (with publish_state), competitors, and disambiguation. Falls back to the draft when nothing is published.

ParameterTypeRequiredDescription
brand any no

publish_vault

Publish a new vault version. Payload shape: `{"sections": {<registry key>: {"content", "publish_state": "public"|"internal", "evidence_url"?}}, "competitors": [{name, url, competitor_type: "direct"|"indirect_adjacent"|"legacy_category", is_primary}], "disambiguation": {<one of the six field keys>: [str]}, "parent_brand_id": "<brand UUID>" | null}`. The full schema, including every section and disambiguation key, is in this tool's input schema. **Presence means replace; omission means keep.** Omitted `sections` copy forward from the active version. Omitted `competitors`, `disambiguation` and `parent_brand_id` PRESERVE the current living state; to change them, send the complete list/object (a present object replaces the whole set), or `[]` / `{}` to clear. `parent_brand_id` is a single ID, not a set: send the parent's brand UUID to set it, or null to clear it. Sending only the fields you are adding will delete the rest of that set. `alternate_domains` is the exception: it carries forward when omitted and cannot be changed through the API. `additional_context` is user-authored only (never filled by onboarding) and defaults to `publish_state: "internal"`: it shapes report questions but does not reach the Brand Index unless explicitly published. It is capped at 20,000 characters. Competitor URLs may omit the scheme (`example.com`, `example.com/pricing`); they are stored as https://. Rows whose URL does not resolve are dropped, never fatal. Measurement is not re-triggered by publishing — runs are scheduled in the app. Publishing changes what the world sees, so this tool does not guess which brand it is for: state `brand`, and **confirm the brand with the user before calling it** — name it in the confirmation ("publish to Acme?"), and if the organization has more than one brand, never infer which one they meant.

ParameterTypeRequiredDescription
payload object yes The complete `publish_vault` payload. Omitted `sections` copy forward. Omitted `competitors`, `disambiguation` and `parent_brand_id` preserve the current living state; an explicit list/object/ID replaces it, and `[]` / `{}` / `null` clears it. A present `disambiguation` object replaces the whole set (except `alternate_domains`, which carries forward when omitted).
brand any no

list_vault_versions

Version history of the brand's vault, newest first (metadata only).

ParameterTypeRequiredDescription
brand any no

get_vault_version

One vault version snapshot by number: metadata + the full section rows.

ParameterTypeRequiredDescription
version integer yes
brand any no

list_recommendations

All recommendations for the brand, newest first. Optional filters: status (todo|done|dismissed), effort (low|medium|high).

ParameterTypeRequiredDescription
status any no
effort any no
brand any no

act_on_recommendation

Act on a recommendation: status todo|done|dismissed; acted_at (optional ISO-8601) backdates the completion. Provide status and/or acted_at. This writes, so it names its brand: state `brand` rather than letting it be inferred, and when the organization has more than one, confirm with the user which brand's recommendation this is.

ParameterTypeRequiredDescription
rec_id string yes
status any no
acted_at any no
brand any no

list_reports

All measurement reports for the brand, newest version first. Reports are read-only — runs are triggered in the app, never here.

ParameterTypeRequiredDescription
brand any no

get_report_status

Whether this brand can generate a report now, and why not if it cannot. Returns the per-brand free-report budget (`budget`, `used`, `remaining`), `unlock_at` when the budget is spent, the blocking `gate` when one applies (`vault_not_published` | `report_budget_exhausted` | `vault_stale`), the latest run, and `can_generate` (false while a run is in flight). A request the worker has not yet turned into a run appears as `reports.queued` with the `request_id` generate_report returned, so an immediate poll cannot mistake the previous report for the new one. This tool starts no run. Tell the user what blocks a report when `gate` is set; when it is not, call generate_report after confirming with them that it should spend one of their reports.

ParameterTypeRequiredDescription
brand any no

generate_report

Generate a new report for this brand now. Queues the same run the app's Generate button queues, spending one of the brand's free reports (three per brand per rolling 30 days). The profile must be published and current (`vault_not_published` / `vault_stale`), the budget must have room (`report_budget_exhausted`), and no other run may be in flight (`run_in_progress`); a closed gate returns the same message the app shows. This spends a report, so name the brand explicitly and **confirm with the user before calling it** — say which brand and how many reports remain (call get_report_status first). A run takes minutes: this returns as soon as it is queued (`queued: true`, or `already_queued: true` when the same minute's request already exists) with a `request_id`; get_report_status follows it, reporting that id under `reports.queued` until the worker creates the run, then the run under `reports.latest_run`.

ParameterTypeRequiredDescription
brand any no

get_report

One report: frozen summary metrics, the per-model breakdown, the model panel snapshot, and the run block (trigger, timing).

ParameterTypeRequiredDescription
report_id string yes
brand any no

get_report_questions

Question Analysis for one report: every question with per-model answers and judgments. Pass question_id to narrow to a single question.

ParameterTypeRequiredDescription
report_id string yes
question_id any no
brand any no

get_report_sources

Sources for one report: per-domain citation aggregation with owned / competitor / third-party classification.

ParameterTypeRequiredDescription
report_id string yes
brand any no

get_attribution

Attribution for the brand: metric trend across report versions plus the acted-on recommendation timeline.

ParameterTypeRequiredDescription
brand any no

Related

The keyed REST API covers the same records over plain HTTP, for programs that would rather not speak MCP.