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.
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.
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.
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.
get_vault
The brand's active vault: all sections (with publish_state),
competitors, and disambiguation. Falls back to the draft when nothing is
published.
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.
list_vault_versions
Version history of the brand's vault, newest first (metadata only).
get_vault_version
One vault version snapshot by number: metadata + the full section rows.
list_recommendations
All recommendations for the brand, newest first. Optional filters:
status (todo|done|dismissed), effort (low|medium|high).
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.
list_reports
All measurement reports for the brand, newest version first. Reports
are read-only — runs are triggered in the app, never here.
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.
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`.
get_report
One report: frozen summary metrics, the per-model breakdown, the model
panel snapshot, and the run block (trigger, timing).
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.
get_report_sources
Sources for one report: per-domain citation aggregation with
owned / competitor / third-party classification.
get_attribution
Attribution for the brand: metric trend across report versions plus the
acted-on recommendation timeline.