> ## 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 server

> Connect OpenLens to your AI agent. One OAuth sign-in, no API keys to copy.

OpenLens exposes a remote MCP server so agents can onboard clients, run visibility scans, read every metric the dashboard shows, and manage projects on your behalf. One OAuth sign-in, no API keys to copy.

## Quick reference

|                    |                                              |
| ------------------ | -------------------------------------------- |
| **Server URL**     | `https://openlens.com/mcp`                   |
| **Transport**      | Streamable HTTP                              |
| **Auth**           | OAuth 2.1 (browser flow)                     |
| **stdio fallback** | `npx -y mcp-remote https://openlens.com/mcp` |

## Video walkthrough

Watch the full setup end to end. This walkthrough covers **Claude** (Claude.ai, Claude Desktop, and Claude Code) — for other clients, follow the matching tab below.

<iframe src="https://www.loom.com/embed/4cb61fd12f4b4da1a4c1482960d4b615" width="100%" height="450" frameBorder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen />

## Install in your client

<Tabs>
  <Tab title="Claude.ai (Team or Enterprise)">
    Open [claude.ai/customize/connectors](https://claude.ai/customize/connectors), click **Add custom connector**, and enter `https://openlens.com/mcp`. The connector then shows up in Claude.ai web, Claude Desktop, and Claude Code automatically.
  </Tab>

  <Tab title="Claude Desktop (Free or Pro)">
    In Claude, open **Settings → Connectors → Add custom connector**, enter `https://openlens.com/mcp`, and connect.
  </Tab>

  <Tab title="Claude Code">
    In your terminal, run:

    ```bash theme={null}
    claude mcp add openlens --transport http https://openlens.com/mcp
    ```

    Open Claude Code, run `/mcp`, pick `openlens`, and finish the browser sign-in.
  </Tab>

  <Tab title="ChatGPT (Developer Mode)">
    Turn on **Settings → Connectors → Advanced → Developer Mode**, then **Add custom connector** with URL `https://openlens.com/mcp` and Auth set to OAuth.
  </Tab>

  <Tab title="Cursor">
    [One-click install](cursor://anysphere.cursor-deeplink/mcp/install?name=OpenLens\&config=eyJ1cmwiOiJodHRwczovL29wZW5sZW5zLmNvbS9tY3AifQ==). Or add manually to `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "openlens": { "url": "https://openlens.com/mcp" }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code (Copilot Chat)">
    Add to `.vscode/mcp.json`:

    ```json theme={null}
    {
      "servers": {
        "openlens": { "type": "http", "url": "https://openlens.com/mcp" }
      }
    }
    ```
  </Tab>

  <Tab title="Codex CLI">
    In your terminal, run:

    ```bash theme={null}
    codex mcp add openlens --url https://openlens.com/mcp
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "openlens": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://openlens.com/mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Zed">
    Add to `~/.config/zed/settings.json`:

    ```json theme={null}
    {
      "context_servers": {
        "openlens": {
          "source": "custom",
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://openlens.com/mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other clients">
    Point it at `https://openlens.com/mcp` if it supports streamable HTTP. Otherwise wrap it with the stdio shim:

    ```bash theme={null}
    npx -y mcp-remote https://openlens.com/mcp
    ```
  </Tab>
</Tabs>

## Verify it works

From any client, ask the agent:

<Note>
  "List my OpenLens projects."
</Note>

The agent should call `list_projects` and return at least one row.

## Troubleshooting

* **Auth error or "needs client registration":** sign out of your client and reconnect. The OAuth handshake has to complete on first install.
* **Stale token:** clear the mcp-remote cache with `rm -rf ~/.mcp-auth/` and retry.
* **VS Code: "server failed to start":** Node 18+ has to be on PATH so the editor can spawn `npx`.
* **Anything else:** email [contact@aibread.com](mailto:contact@aibread.com) with the client, version, and the exact error.

## Available tools

The server exposes 54 tools across project setup, brands, platforms, topics, prompts, prompt attributes, runs, Site / Agent Readiness, AI Index Coverage, content audit, visibility analytics, workstreams, and scheduling. Each is annotated read-only or write so MCP clients can auto-permission reads and confirm writes. See the [tools reference](/mcp/tools) for the full list grouped by surface.