> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mentionlab.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect MentionLab to AI tools using the Model Context Protocol

## Overview

MentionLab provides a remote [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server
that lets you work with your brand analytics directly from AI tools like Claude, Cursor, and
Windsurf.

It is a hosted, remote server — there is nothing to install and no local process to run. You point
your client at a URL, sign in through MentionLab, and your assistant can manage projects, queries,
entities and tags, and query every analytics surface in plain language.

<Warning>
  The MCP server is currently in beta and is subject to breaking changes.
</Warning>

## Server URL

```
https://mcp.mentionlab.io/mcp
```

Some clients cap how many tools they will load. For those, use the **lean** URL instead — see
[Choosing a URL](#choosing-a-url).

```
https://mcp.mentionlab.io/mcp?profile=lean
```

## Authentication

The server uses **OAuth 2.1** with dynamic client registration and PKCE. On first connection your
client opens a browser window, you sign in to MentionLab and approve access, and the client stores
the token. There are no API keys to create and nothing to paste.

Your assistant sees exactly what your MentionLab account sees — the same organizations, projects
and permissions. To revoke access, disconnect the server in your client.

## Connect your client

<Tabs>
  <Tab title="Claude">
    Claude Desktop, Claude web and the Claude mobile apps all connect the same way — as a **custom
    connector**. There is no config file to edit.

    1. Open **Settings → Connectors**.
    2. Click **Add custom connector**.
    3. Paste the URL:
       ```
       https://mcp.mentionlab.io/mcp
       ```
    4. Click **Add**, then **Connect** and sign in to MentionLab when the browser opens.

    The connector then appears in the attachments menu of any chat.
  </Tab>

  <Tab title="Claude Code">
    Run this in your terminal:

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

    Then run `/mcp` inside Claude Code and choose **Authenticate** to complete the browser sign-in.
  </Tab>

  <Tab title="Cursor">
    Use the **lean** URL — Cursor only loads the first 40 tools it is offered.

    Add this to `.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "mentionlab": {
          "url": "https://mcp.mentionlab.io/mcp?profile=lean"
        }
      }
    }
    ```

    Then open **Settings → MCP** and click **Login** next to the MentionLab server.
  </Tab>

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

    ```json theme={null}
    {
      "mcpServers": {
        "mentionlab": {
          "serverUrl": "https://mcp.mentionlab.io/mcp?profile=lean"
        }
      }
    }
    ```

    Then click **Refresh** in the MCP panel and complete the browser sign-in.
  </Tab>

  <Tab title="Other clients">
    Any client with remote MCP + OAuth support works. Point it at
    `https://mcp.mentionlab.io/mcp` and let it discover the OAuth configuration from
    `/.well-known/oauth-protected-resource`.

    If the client caps tool counts or has no tool-search of its own, use the `?profile=lean` URL.
  </Tab>
</Tabs>

## Choosing a URL

The server exposes a large tool surface. Which URL you use decides how much of it is loaded up
front — the capabilities themselves are identical either way.

| URL                  | Use it when                                                                              | Behaviour                                          |
| -------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `…/mcp`              | Your client loads tool schemas on demand (Claude apps, Claude Code)                      | Every tool is listed                               |
| `…/mcp?profile=lean` | Your client has a tool cap or loads every schema up front (Cursor, ChatGPT, most others) | A small core is listed; the rest stay one hop away |

<Info>
  Nothing is lost on the lean profile. The assistant can find any hidden tool with `search_tools`,
  load it with `describe_tool`, or call it directly through `run_code`. If your client shows a
  truncated tool list or complains about too many tools, switch to the lean URL.
</Info>

## Example usage

Once connected, work in plain language:

> "Show me my brand's visibility trend for the last 30 days."

> "Which domains cite my brand most frequently?"

> "Compare sentiment across my top 5 competitors."

> "Create a new query: 'What is the best CRM for startups?' with the tag 'Product'."

<Tip>
  Ask the assistant to call `guide` first when starting a bigger analysis. It returns the domain
  model and a set of workflow playbooks, which makes the follow-up answers noticeably better.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The client asks me to sign in again on every session">
    Your client is not persisting the OAuth token. Reconnect the server; if it keeps happening,
    remove and re-add it so a fresh client registration is issued.
  </Accordion>

  <Accordion title="Only some tools show up, or the client says there are too many tools">
    Switch to `https://mcp.mentionlab.io/mcp?profile=lean`.
  </Accordion>

  <Accordion title="Requests fail with 401 unauthorized">
    The access token expired or was revoked. Disconnect and reconnect the server to re-authorize.
  </Accordion>

  <Accordion title="A tool returns 'result too large'">
    Ask the assistant to re-run the same call inside `run_code` and aggregate there, so only the
    summary comes back.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="REST API" icon="code" href="/rest-api/getting-started">
    Learn the basics of the MentionLab REST API.
  </Card>

  <Card title="Core Concepts" icon="lightbulb" href="/guides/core-concepts">
    Understand projects, queries, entities, and tags.
  </Card>
</CardGroup>