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

# MCP server

> Connect AI coding agents to the Superblocks platform via the Model Context Protocol

The Superblocks MCP server lets AI coding agents (Cursor, Claude Code, Windsurf, and others) interact with your Superblocks organization directly. Agents can list applications, manage integrations, deploy apps, manage access control, and more — all through the [Model Context Protocol](https://modelcontextprotocol.io/).

## Quickstart

Connect to the hosted Superblocks MCP server — no install required. You'll need your Superblocks API token, which you can find in [Personal Settings > API Key](https://app.superblocks.com/personal-settings#apiKey).

<Tabs>
  <Tab title="Cursor">
    <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=superblocks&config=eyJ1cmwiOiJodHRwczovL2FwcC5zdXBlcmJsb2Nrcy5jb20vbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIFlPVVJfVE9LRU4ifX0%3D">
      <img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install MCP Server" noZoom />
    </a>

    Click the button to install, then replace `YOUR_TOKEN` with your API token in **Cursor Settings > MCP**.

    Or add it manually:

    ```json theme={null}
    {
      "mcpServers": {
        "superblocks": {
          "url": "https://app.superblocks.com/mcp",
          "headers": {
            "Authorization": "Bearer <superblocks-access-token>"
          }
        }
      }
    }
    ```
  </Tab>

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

    ```bash theme={null}
    claude mcp add --transport http \
      --header "Authorization: Bearer <superblocks-access-token>" \
      superblocks https://app.superblocks.com/mcp
    ```
  </Tab>

  <Tab title="Other MCP clients">
    Point your MCP client at the following URL with an `Authorization` header:

    ```
    URL: https://app.superblocks.com/mcp
    Header: Authorization: Bearer <superblocks-access-token>
    ```
  </Tab>
</Tabs>

## What can the MCP server do?

Once connected, AI agents can use the following capabilities through natural language:

| Category            | Examples                                                          |
| ------------------- | ----------------------------------------------------------------- |
| **Applications**    | List apps, view structure, check commit history, deploy, undeploy |
| **Integrations**    | List, create, update, and delete integrations                     |
| **Access control**  | View and manage application, workflow, and job permissions        |
| **Role management** | Assign and update org-level roles for users and groups            |
| **Organization**    | View org summary, list members, manage builder seats              |
| **Folders**         | Create, update, and delete folders                                |
| **Audit**           | Query audit events and compute aggregated metrics                 |
| **Chat history**    | Retrieve Clark AI conversation history for any application        |
| **Billing**         | View plan summary and usage                                       |
| **Knowledge**       | List and view Knowledge entries                                   |

## Alternative: Local MCP server

If you prefer to run the MCP server locally, you can use the CLI-based setup instead. This requires Node.js 22+ and an API token.

<Steps>
  <Step title="Authenticate">
    Run the following command, replacing `<token>` with your Superblocks API key. You can find your API key in [Personal Settings](https://app.superblocks.com/personal-settings#apiKey).

    ```bash theme={null}
    npx -y @superblocksteam/mcp-server login --token <token>
    ```
  </Step>

  <Step title="Install the MCP server">
    Run the setup command for your IDE:

    <Tabs>
      <Tab title="Cursor">
        ```bash theme={null}
        npx -y @superblocksteam/mcp-server setup --client cursor
        ```

        This writes the MCP server configuration to `~/.cursor/mcp.json`.
      </Tab>

      <Tab title="Claude Code">
        ```bash theme={null}
        npx -y @superblocksteam/mcp-server setup --client claude
        ```

        This writes the MCP server configuration to `~/.claude.json`.
      </Tab>

      <Tab title="Other MCP clients">
        ```bash theme={null}
        npx -y @superblocksteam/mcp-server setup
        ```

        This prints the JSON configuration to stdout. Copy it into your MCP client's configuration file.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Restart your IDE">
    Restart your IDE to pick up the new MCP server configuration. You should see **superblocks** listed as a connected MCP server.
  </Step>
</Steps>

If you already have the [Superblocks CLI](/building-with-clark/developing-apps-in-code) installed, you can set up the local MCP server through it instead:

```bash theme={null}
superblocks login
superblocks mcp setup --client cursor
```

Use `--dry-run` to preview the configuration without modifying any files:

```bash theme={null}
npx -y @superblocksteam/mcp-server setup --client cursor --dry-run
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Hosted server: authentication errors">
    Verify your API token is correct. You can find or regenerate it in [Personal Settings > API Key](https://app.superblocks.com/personal-settings#apiKey).

    Make sure the `Authorization` header uses the `Bearer` prefix:

    ```
    Authorization: Bearer sb_xxxxxxxxxx
    ```

    If the token was recently regenerated, update it in your MCP client configuration and restart your IDE.
  </Accordion>

  <Accordion title="Local server: not connecting">
    Verify the server starts correctly by running it directly:

    ```bash theme={null}
    npx -y @superblocksteam/mcp-server --help
    ```

    If you see the usage text, the server is installed correctly. Restart your IDE and check that the MCP server appears in your IDE's MCP server list.
  </Accordion>

  <Accordion title="Local server: authentication errors">
    Re-run the login command to refresh your token:

    ```bash theme={null}
    npx -y @superblocksteam/mcp-server login --token <token>
    ```

    Your token is stored at `~/.superblocks/auth.json`. You can verify it exists:

    ```bash theme={null}
    cat ~/.superblocks/auth.json
    ```
  </Accordion>

  <Accordion title="Local server: Node.js version requirements">
    The local MCP server requires Node.js 22 or later. Check your version:

    ```bash theme={null}
    node --version
    ```

    The hosted server at `app.superblocks.com/mcp` has no local requirements.
  </Accordion>
</AccordionGroup>