MCP tools reference

Every tool is scoped to the authenticated user’s projects. All require a valid OAuth session and operate with the same permissions as the web UI. Each tool is annotated read-only or write: read-only tools run without a per-call confirmation; tools that modify or delete data prompt before running.

The in-app Agent uses a private MCP surface at /api/agent/mcp and adds agent-only tools such as create_document. Those private tools are not available through the public OAuth /mcp server.

Async status

Async run and audit tools return one lifecycle status on the existing payload object. The agent-facing status values are queued, running, completed, failed, canceling, canceled, stale, unknown, and none for empty prompt-run responses. MCP does not expose partial as a status; incomplete output remains visible through existing fields such as platform response counts, content-audit progress, results_truncated, and page/result counts. stale is derived at read/list time from running or interrupted records and feature-specific stale thresholds; it is not a stored database status.

Connection

Tool	Description
`whoami`	Report the connected user and organization (workspace) this MCP connection is bound to: org name, org id, plan tier, and your role. Call it first, before any tool that creates, updates, or deletes data, to confirm you are operating in the intended workspace. A binding of `personal_workspace_fallback` means the OAuth token carried no organization claim, so you are in a personal workspace; reconnect and select the org if that was not intended.

Project & client setup

Tool	Description
`setup_client`	Create a new OpenLens project with own brand, competitors, topics, custom prompt attributes, and generated prompts.
`list_projects`	List the user’s OpenLens projects.
`update_project_settings`	Update name, URL, location, languages, active platforms, or generated prompts. `refresh_prompts` tops-up or recreates prompts.
`delete_project`	Archive one project. History is preserved.

Brands

Tool	Description
`list_brands`	List the own brand and competitors tracked for a project.
`add_competitors`	Add one or more competitor brands in one batch. Names matching an existing or the own brand are skipped.
`delete_competitors`	Soft-delete one or more competitor brands by ID in one batch. Past mentions are preserved; the own brand cannot be deleted this way.

Platforms

Tool	Description
`list_platforms`	List the AI platforms the user is entitled to.

Topics

Tool	Description
`list_topics`	List tracked topics for a project.
`add_topics`	Add one or more topics in one batch, each starting background prompt generation.
`delete_topics`	Soft-delete one or more topics by ID in one batch. They stop running; past responses are preserved.

Prompts

Tool	Description
`list_prompts`	List active and inactive prompts, optionally scoped to one topic.
`add_prompts`	Add one or more manual prompts to existing topics in one batch. Attributes are required and must come from `list_prompt_attributes`.
`set_prompts_active`	Activate or deactivate one or more prompts by ID in one batch, all the same direction. Historical results are kept.
`update_prompt_templates`	Edit one or more prompts’ text and/or attributes by ID in one batch. Editing a prompt with run history clones it and returns `requires_confirmation`.
`delete_prompts`	Soft-delete one or more prompts by ID in one batch. Historical responses are retained; use `set_prompts_active` for reversible deactivation.

Prompt attributes

Tool	Description
`list_prompt_attributes`	Built-in + custom attributes for a project.
`add_prompt_attributes`	Add one or more custom attributes in one batch. Existing, archived, or reserved values are skipped.
`archive_prompt_attributes`	Archive one or more custom attributes in one batch. Historical labels are preserved; built-in and language attributes cannot be archived.
`unarchive_prompt_attributes`	Restore one or more archived custom attributes in one batch.

Prompt runs

Tool	Description
`run_prompts`	Start a run. Returns immediately with `status`. Poll `get_run_status` every ~30s while status is `queued`, `running`, or `canceling`.
`cancel_run`	Cancel a running prompt run. Safe for already-terminal runs.
`get_run_status`	Get status. Pass `run_id` for a specific run; omit it for the latest run. Unknown explicit run IDs return `RUN_NOT_FOUND`; projects with no runs return `status: none`.
`list_runs`	List recent runs with their IDs and canonical lifecycle `status`.

To read historical analytics, call list_runs first and pass a completed run’s run_id to get_visibility, get_topic_visibility, get_attribute_breakdown, get_engine_patterns, get_prompt_performance, get_citations, or get_mentions. Omit run_id to use the latest usable run. Those tools reject runs from another project and runs that have not completed. get_prompt_results also accepts run_id and can expose an in-progress run’s partial output. Comparing citations and visibility across runs can show correlation, but it does not prove that a source caused a visibility change.

Site / Agent Readiness

Tool	Description
`run_readiness_check`	Start a Site / Agent Readiness crawl for a project. Returns the new run’s id, status, and effective scope configuration. Consumes monthly page allowance.
`get_readiness_run`	Get status, score, summary, grouped check counts, and per-check detail for a readiness run (detail may be redacted on the free tier).
`list_readiness_runs`	List recent Site / Agent Readiness runs for a project, newest first (latest 50).

AI Index Coverage

Tool	Description
`run_ai_index_coverage`	Start an AI Index Coverage run for a project URL. Returns the run id, status, effective scope, allowance summary, and polling metadata.
`get_ai_index_coverage_run`	Get one AI Index Coverage run’s status, score, per-platform coverage summary (`indexed`, `not_indexed`, `unknown`), gated classified page-level gaps, and polling metadata.
`list_ai_index_coverage_runs`	List recent AI Index Coverage runs for one project, including ids, status, scores, page counts, timestamps, and error summaries.

Visibility & analytics

Tool	Description
`get_visibility`	Brand visibility for the latest usable run or a specific completed run. Supports `overview`, `by_topic`, `by_platform`.
`get_topic_visibility`	Detailed visibility for one topic in the latest usable run or a specific completed run.
`get_trends`	Multi-brand visibility trends over the last N days.
`get_prompt_results`	Raw AI response text for the latest usable run or a specific run, with optional filters.
`get_prompt_performance`	Rank prompts by appearance, coverage, position, citations, and sentiment in the latest usable run or a specific completed run.
`get_attribute_breakdown`	Per-attribute brand sentiment and evidence for one topic in the latest usable run or a specific completed run. These are response attributes (what AI says about each brand), distinct from prompt-tag attributes.
`get_engine_patterns`	Compare how each platform sources and structures answers in the latest usable run or a specific completed run.
`get_citations`	Top cited domains for the latest usable run or a specific completed run, with optional filters.
`get_mentions`	Own-brand mention summaries grouped by topic for the latest usable run or a specific completed run.

Google integrations

Both tools read through the organization’s Google connection and the project’s assigned property, set up in the web UI (Site Readiness Performance). When setup is incomplete they return NOT_CONNECTED or NOT_CONFIGURED with the exact next step instead of failing. Read-only, both of them.

Tool	Description
`get_gsc_search_analytics`	Google Search Console search analytics for a project: clicks, impressions, CTR, position, plus top rows by `query` or `page` over 7, 28, or 90 days. Live from Google, cached about an hour. Headline totals use by-property aggregation and match the GSC UI. GSC reporting lags 2 to 3 days behind real time.
`get_ga4_ai_traffic`	GA4 sessions and key events from AI referrers (ChatGPT, Perplexity, Gemini, Claude, Copilot, Grok, DeepSeek) against site totals, over 7, 28, or 90 days. Referrer-based, so it is a lower bound. Native apps and pasted links send no referrer.

Scheduling

Tool	Description
`get_schedule`	Inspect the scheduled prompt-run settings for one project.
`update_schedules`	Update scheduled-run settings for one or more projects in one batch, each taking at least one of `enabled`, `frequency`, or `hour_utc`.

Content audit

Tool	Description
`run_content_audit`	Start a content audit for a project (whole site or single page). Returns immediately — poll `get_content_audit_status`. Consumes monthly page allowance (same as the web app).
`get_content_audit_status`	Poll audit status and progress (scored vs planned pages) without full scores or fix detail.
`get_content_audit_results`	Fetch plan-gated audit results: scores, dimension summaries, and prioritized fixes when entitled.
`list_content_audits`	List recent content audits for a project (id, target, status, score, page count, started time).

Documentation

These search the OpenLens documentation itself, so an agent can answer product questions and recommend next steps without guessing. Both are read-only and return ranked doc sections, each with a deep-link URL and a snippet.

Tool	Description
`docs_search`	Search the full documentation (definitions, pricing, web UI manual, MCP/API reference) with BM25 ranking. Returns the most relevant sections for a query.
`happy_paths`	Search only the “how you’re meant to use OpenLens” docs (onboarding, quickstart, recommended workflows). Best for open-ended “what should I do now?” guidance rather than syntax or reference lookups.

Get started

Pricing

Web UI manual

Organizations

How-tos

MCP server

MCP tools reference

Async status

Connection

Project & client setup

Brands

Platforms

Topics

Prompts

Prompt attributes

Prompt runs

Site / Agent Readiness

AI Index Coverage

Visibility & analytics

Google integrations

Scheduling

Content audit

Documentation

​Async status

​Connection

​Project & client setup

​Brands

​Platforms

​Topics

​Prompts

​Prompt attributes

​Prompt runs

​Site / Agent Readiness

​AI Index Coverage

​Visibility & analytics

​Google integrations

​Scheduling

​Content audit

​Documentation

Async status

Connection

Project & client setup

Brands

Platforms

Topics

Prompts

Prompt attributes

Prompt runs

Site / Agent Readiness

AI Index Coverage

Visibility & analytics

Google integrations

Scheduling

Content audit

Documentation