> ## Documentation Index > Fetch the complete documentation index at: https://docs.openlens.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP tools reference > Every tool the OpenLens MCP server exposes, grouped by surface. The MCP server registers 54 tools 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. ## 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. Poll `get_run_status` every \~30s until `completed` or `failed`. | | `cancel_run` | Cancel a running prompt run. Safe for already-terminal runs. | | `get_run_status` | Get status. Omit `run_id` for the latest run. | | `list_runs` | List recent runs (running, completed, failed, cancelled, interrupted). | ## 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, running 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, statuses, scores, page counts, timestamps, and error summaries. | ## Visibility & analytics | Tool | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_visibility` | Brand visibility for the latest usable run. Supports `overview`, `by_topic`, `by_platform`. | | `get_topic_visibility` | Detailed visibility for one topic. | | `get_trends` | Multi-brand visibility trends over the last N days. | | `get_prompt_results` | Raw AI response text, with optional filters. | | `get_prompt_performance` | Rank prompts by appearance, coverage, position, citations, sentiment. | | `get_attribute_breakdown` | Per-attribute brand sentiment and evidence for one topic. 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. | | `get_citations` | Top cited domains, with optional filters. | | `get_mentions` | Own-brand mention summaries grouped by topic. | ## Workstreams | Tool | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------- | | `list_workstreams` | List goal-tracked workstreams. | | `get_workstream` | Header + 30-day sparkline + 90-day trend series. | | `get_workstream_breakdown` | Prompt-level movers and competitor share. | | `create_workstreams` | Create one or more workstreams from topics and/or prompt attributes in one batch. Optional initial goal. | | `update_workstreams` | Update one or more workstreams' name, topics, or attributes by ID in one batch. Goals are changed separately. | | `archive_workstreams` | Archive one or more workstreams by ID in one batch. Reverse with `unarchive_workstreams`. | | `unarchive_workstreams` | Restore one or more archived workstreams by ID in one batch. | | `update_workstream_goals` | Append a new current goal to one or more workstreams by ID in one batch. Past goals stay in history. | ## 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). |