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

# MCP Setup Guide

> Step-by-step guide to connect Claude Desktop, Cursor, or VS Code to Superlines.

## Prerequisites

Before you begin, make sure you have:

1. A **paid Superlines plan** (Starter, Growth, or Enterprise)
2. An **API key** from Organization Settings (format: `sl_live_...`) — not required for OAuth on Claude.ai
3. An MCP-compatible client installed

## Connection methods

| Method                | Best for                          | Protocol           |
| --------------------- | --------------------------------- | ------------------ |
| **OAuth (Claude.ai)** | Claude.ai web — no API key needed | OAuth 2.0 + SSE    |
| **SSE (URL-based)**   | Claude Desktop, most clients      | Server-Sent Events |
| **Local npx**         | Cursor, VS Code, advanced setups  | Standard I/O       |

## Option 1: OAuth setup (Claude.ai)

Connect Superlines directly to Claude.ai through OAuth — no API key required. You sign in with your Superlines account and authorize access.

<Steps>
  <Step title="Open Claude.ai settings">
    Go to [claude.ai](https://claude.ai) → **Settings** → **Connectors** → **Add custom connector**.
  </Step>

  <Step title="Enter the server details">
    * **Name:** `Superlines`
    * **URL:** `https://mcpsse.superlines.io`
    * Open **Advanced settings** and set **OAuth Client ID** to `anthropic-claude`
    * Leave **OAuth Client Secret** blank
    * Click **Add**
  </Step>

  <Step title="Authorize access">
    Claude will redirect you to the Superlines authorization page. Sign in with your Superlines account, review the requested permissions, select which brands to share, and click **Authorize Access**.
  </Step>

  <Step title="Start using Superlines">
    Back in Claude, start a new conversation and try: *"List my Superlines brands"*
  </Step>
</Steps>

<Tip>
  OAuth connections are scoped to the brands you select during authorization. You can revoke access at any time from your Superlines account settings.
</Tip>

## Option 2: SSE / URL-based setup

The simplest approach — just add a URL to your client's configuration.

**Connection URL:**

```
https://mcpsse.superlines.io?token=YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

<Tabs>
  <Tab title="Claude Desktop">
    <Steps>
      <Step title="Open Claude Desktop settings">
        Go to **Settings → Developer → Edit Config** to open:

        ```
        ~/Library/Application Support/Claude/claude_desktop_config.json
        ```
      </Step>

      <Step title="Add the Superlines server">
        ```json theme={null}
        {
          "mcpServers": {
            "superlines": {
              "url": "https://mcpsse.superlines.io?token=YOUR_API_KEY",
              "transport": "sse"
            }
          }
        }
        ```
      </Step>

      <Step title="Restart Claude Desktop">
        Save and fully restart the app for changes to take effect.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Open or create .cursor/mcp.json">
        This file lives in your project root or global config directory.
      </Step>

      <Step title="Add the Superlines server">
        ```json theme={null}
        {
          "mcpServers": {
            "superlines": {
              "url": "https://mcpsse.superlines.io?token=YOUR_API_KEY",
              "transport": "sse"
            }
          }
        }
        ```
      </Step>

      <Step title="Restart Cursor" />
    </Steps>
  </Tab>

  <Tab title="VS Code">
    <Steps>
      <Step title="Open your MCP configuration">
        This depends on your MCP extension.
      </Step>

      <Step title="Add the Superlines server">
        ```json theme={null}
        {
          "mcpServers": {
            "superlines": {
              "url": "https://mcpsse.superlines.io?token=YOUR_API_KEY",
              "transport": "sse"
            }
          }
        }
        ```
      </Step>

      <Step title="Restart VS Code" />
    </Steps>
  </Tab>
</Tabs>

## Option 3: Local npx setup

For clients that prefer local process-based connections, use the npm package.

<Note>
  Requires **Node.js** installed on your machine.
</Note>

<Tabs>
  <Tab title="Claude Desktop">
    ```json theme={null}
    {
      "mcpServers": {
        "superlines": {
          "command": "npx",
          "args": ["-y", "@superlines/mcp-server"],
          "env": {
            "SUPERLINES_API_KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor / VS Code">
    ```json theme={null}
    {
      "mcpServers": {
        "superlines": {
          "command": "npx",
          "args": ["-y", "@superlines/mcp-server"],
          "env": {
            "SUPERLINES_API_KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## API key permissions

By default, API keys have **read-only** access — they can query analytics data but cannot modify your account. To use the [Account Management](/mcp/tools#account-management) tools (creating brands, adding prompts, etc.), you need to enable write permissions on your API key.

### How to enable write permissions

<Steps>
  <Step title="Go to Organization Settings">
    Open **Organization Settings → API Keys** in the Superlines dashboard.
  </Step>

  <Step title="Edit your API key">
    Click on the API key you use for MCP and open its permissions settings.
  </Step>

  <Step title="Enable write permissions">
    Toggle on the permissions you need:

    * **`write:brands`** — allows creating new brands/domains
    * **`write:prompts`** — allows adding, pausing, unpausing prompts and managing labels
  </Step>

  <Step title="Save and reconnect">
    Save your changes. No client restart is needed — permissions take effect immediately.
  </Step>
</Steps>

### Available permissions

| Permission      | Grants access to                                                          |
| --------------- | ------------------------------------------------------------------------- |
| `read`          | All analytics and reporting tools (default, always included)              |
| `write:brands`  | `create_brand`, `get_brand_setup_status`                                  |
| `write:prompts` | `add_prompts`, `pause_prompts`, `unpause_prompts`, `update_prompt_labels` |

<Info>
  Write operations are **rate-limited** and **audit-logged** for security. Brand creation is limited to 5 per hour, and prompt operations to 100 per hour per organization. All write actions are recorded in your organization's audit log.
</Info>

<Warning>
  Deletion is intentionally not supported via MCP to prevent accidental data loss. Use `pause_prompts` to temporarily disable prompts instead.
</Warning>

***

## Verify the connection

After setting up your client:

1. Start a new conversation
2. Ask: *"List my Superlines brands"*
3. The AI should call the `list_brands` tool and show your brands

If it works, try:

* *"Show me my brand visibility for the last 30 days"*
* *"Who are my top competitors?"*
* *"Find content opportunities where I have low visibility"*

## Troubleshooting

| Issue                   | Solution                                                                      |
| ----------------------- | ----------------------------------------------------------------------------- |
| "Tool not found"        | Restart your MCP client after configuration changes                           |
| "Authentication failed" | Verify your API key is correct and starts with `sl_live_`                     |
| "No data returned"      | Make sure you have at least one brand with tracked prompts                    |
| "Connection timeout"    | Check your internet connection; the SSE endpoint is at `mcpsse.superlines.io` |
| "Plan not supported"    | MCP requires a paid plan (Starter, Growth, or Enterprise)                     |

<Warning>
  **Never share your API key publicly.** If compromised, revoke it immediately in Organization Settings and generate a new one.
</Warning>

## Resources

* [NPM Package: @superlines/mcp-server](https://www.npmjs.com/package/@superlines/mcp-server)
* [MCP Protocol Specification](https://modelcontextprotocol.io)
* [Available Tools Reference](/mcp/tools)
* Support: [support@superlines.io](mailto:support@superlines.io)