Optimly MCP

Optimly MCP

Product

Optimly MCP

Updated

2026-08-09

Optimly MCP exposes authorized Optimly evidence to MCP-compatible clients over Streamable HTTP.

Not sure whether MCP is the right interface? Compare MCP, the Agent API, and the Optimly Agent in Slack.

Custom agent harnesses should use the versioned Optimly Agent API. MCP remains the compatible interface for MCP-native clients and preserves the same brand isolation, permissions, approval requirements, and execution ledger.

Endpoint

https://scout.optimly.ai/mcp

Claude Code

claude mcp add --transport http optimly-mcp https://scout.optimly.ai/mcp

OAuth-capable clients should follow the HTTP authorization challenge. Optimly supports authorization code flow with PKCE and dynamic client registration. Scripts or clients that do not support MCP OAuth can use an active Optimly brand API key:

Authorization: Bearer osk_your_api_key_here

Never place a brand API key in browser code or the Optimly Connect extension.

Agent API and MCP credentials require paid access. Optimly Platform provides read and non-action capabilities. Governed action workflows require the AI Brand Execution Program, the relevant brand permissions, and explicit approval. A free account cannot generate or use either credential.

Follow the agent-assisted access, payment, authorization, and verification flow.

Brand selection

OAuth sessions can authorize one or more brands. If a user has access to several brands, brand-bound tools require an explicit brand_id. Clients should list accessible brands, ask the user to choose, and retry the intended tool call.

Tool discovery

Treat tools/list as authoritative. The manifest is filtered by the authenticated user's plan, authorized brands, and permissions. Do not hard-code an assumption that every session receives every tool.

Use the existing generated MCP tool reference for current parameters, examples, side effects, and related tools. Write-capable action tools require explicit permissions and follow the approval and execution-ledger workflow described below.

Approval and execution ledger

Every state-changing action against verified brand data runs through a governed, auditable chain. The full parameter reference for each tool is in the MCP tool reference.

1. Register an approver — register_brand_approver

establishes the single verified approval contact for the brand.

1. Propose an immutable action — create_execution_action

for a single Business Profile field, or create_brand_vault_publish_action for an aggregate BrandVault change. The payload is hashed and cannot change after creation.

1. Request approval — request_action_approval sends the

exact payloads to the registered approver; list_pending_approvals shows what is waiting.

1. Record the decision — record_approval_decision

attests the approver's decision with durable evidence. revoke_action_approval withdraws an unused approval.

1. Execute — brand_update for one section, or

brand_publish for an aggregate publish that also refreshes the brand's canonical llms.txt. Both atomically start the action and consume the approval.

1. Record external outcomes — for work executed outside Optimly, use

record_action_started, record_action_succeeded, and record_action_failed; get_action_status and check_action_idempotency verify state before retries.

Working with Optimly Actions

Agents with agent-work permissions collaborate with customers through the shared Optimly Actions inbox: read existing work with get_agent_work before proposing anything, save evidence-backed work with save_recommendation and save_draft, and record explicit customer responses with record_agent_feedback and record_checklist_progress.

Safe agent behavior

• Use the verified Source of Truth for brand facts.
• Distinguish retrieved evidence from inference.
• Do not invent missing claims, selectors, destinations, or conversions.
• Do not publish website changes without the customer's explicit approval and an authorized execution path.
• Use Site Analytics for human activity and Agent Analytics for crawler activity; do not merge them.