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

# MCP for AI Assistants

> Connect Claude, Cowork, ChatGPT, Codex and other AI assistants to Surfacd so they can read your data and run actions on your behalf.

<Note>
  Beta functionality: reach out to support to express interest in our API and MCP servers. Beta users can also browse
  the [API Reference](/api-reference).
</Note>

Surfacd ships an [MCP server](https://modelcontextprotocol.io/), a standard way for AI assistants to read your data and run actions on your behalf, with you approving the connection up front.

Use this endpoint in any remote MCP client:

```text theme={null}
https://app.surfacd.com/mcp
```

When your assistant connects, Surfacd opens a browser authorization flow at `app.surfacd.com/oauth/authorize`. Sign in, review the requested access, then click **Authorize**.

## What the assistant can do

Once connected, the assistant has tools for:

* **Reading:** list teams and projects, show a project's brand rankings, mentions, visibility-over-time, prompts, members, source breakdowns.
* **Writing:** create projects and prompts, archive or share a project, update prompt status or tags, invite or revoke team members.

The assistant acts as **you**. It can do exactly what you can do logged in, and the same per-team permissions apply. It cannot bypass project prompt limits or credit budgets.

## Connect your assistant

<Tabs>
  <Tab title="Claude or Cowork">
    Claude calls remote MCP servers **custom connectors**. The same flow works for Claude, Cowork, and
    Claude Desktop.

    1. Open **Customize > Connectors**.
    2. Click the **+** button next to **Connectors**.
    3. Select **Add custom connector**.
    4. Enter `Surfacd` as the name.
    5. Enter `https://app.surfacd.com/mcp` as the URL.
    6. Complete the Surfacd authorization flow.

    If you're on a managed Claude Team or Enterprise workspace, an owner may need to add or approve the
    connector from organization settings first.

    Once connected, ask Claude something like *"list my Surfacd teams"* or *"summarise this week's brand
    visibility for Acme"*.
  </Tab>

  <Tab title="ChatGPT">
    ChatGPT lists custom MCP servers under **Apps & Connectors**.

    1. Open **Settings > Apps & Connectors > Advanced Settings**.
    2. Enable **Developer Mode**.
    3. Under the developer mode options, click **Connect More** or **Create**.
    4. Enter `Surfacd` as the name.
    5. Enter `https://app.surfacd.com/mcp` as the server URL or HTTPS endpoint.
    6. Authorize Surfacd when ChatGPT asks for permission.
    7. Select Surfacd as a source in your chat.

    When you want ChatGPT to use Surfacd, explicitly ask it to use tools, for example: *"use tools to list
    my Surfacd teams"*. ChatGPT may ask you to approve write actions before they run.
  </Tab>

  <Tab title="Codex">
    Codex shares MCP settings across the Codex CLI, IDE extension, and desktop app.

    In Codex Desktop:

    1. Open **Settings** with `Command+,`.
    2. Go to **MCP Servers**.
    3. Select **Add MCP Server**.
    4. Enter `Surfacd` as the name.
    5. Select **Streamable HTTP**.
    6. Enter `https://app.surfacd.com/mcp` as the URL.
    7. Leave the other settings as their defaults.
    8. Click **Save**.

    If you prefer the CLI, add Surfacd as a streamable HTTP MCP server:

    ```bash theme={null}
    codex mcp add surfacd --url https://app.surfacd.com/mcp
    ```

    Then authenticate with Surfacd:

    ```bash theme={null}
    codex mcp login surfacd
    ```

    Inside a Codex session, run `/mcp` to confirm Surfacd is connected and its tools are listed.
  </Tab>

  <Tab title="Other clients">
    For clients that use JSON configuration, add a server entry pointing at the Surfacd endpoint:

    ```json theme={null}
    {
      "mcpServers": {
        "surfacd": {
          "url": "https://app.surfacd.com/mcp"
        }
      }
    }
    ```

    The exact file location varies per client. Restart the client after editing its configuration; it should
    detect that auth is required and walk you through the same browser authorization step as above.
  </Tab>
</Tabs>

## Disconnect

In Claude or Cowork, go to **Customize > Connectors**, open the Surfacd connector, then disconnect or remove it.

In ChatGPT, go to **Settings > Apps & Connectors**, open Surfacd, then disconnect it. Workspace admins can also disable the connector from workspace settings.

In Codex:

```bash theme={null}
codex mcp logout surfacd
codex mcp remove surfacd
```

In other clients, remove the `surfacd` entry from the config and restart.

To revoke access from the Surfacd side (for example, if a device is lost), visit your **profile page** and revoke the connected application. Calls using that grant stop working immediately.

## Safety notes

* The assistant only sees data from teams you belong to, with the same role you have in each.
* Destructive actions (delete a project, revoke a member) go through the same rules as the UI. A good rule of thumb: ask the assistant to confirm a destructive action before running it.
* Tool calls don't bypass project prompt limits or team credit budgets. If you're at your plan's cap, the assistant gets the same error you'd see in the UI.
* Revoke the connection if you stop using the assistant; reconnecting is one CLI command.

## Looking for the API instead?

If you want to call Surfacd directly from scripts or your own services, you want an [API key](/docs/api-keys) instead. MCP is specifically for AI assistants that speak the protocol.