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

# MCP server

> Give your coding agent direct access to PR review issues, codebase documentation, scan results, scan issue triage, and review learnings.

cubic's MCP server connects your coding agent to cubic's data and workflows: PR review issues, AI-generated codebase documentation, codebase scan results, scan issue triage, and team review patterns.

<Note>
  The MCP server requires a cubic account with access to at least one repository. You must be a
  member of the repository's installation to access its data.
</Note>

## Endpoint

Use this exact URL:

```text theme={null}
https://www.cubic.dev/api/mcp
```

<Warning>
  Some MCP clients compare the protected resource URL exactly. Use `https://www.cubic.dev/api/mcp`,
  not `https://cubic.dev/api/mcp`.
</Warning>

## Authentication

Use OAuth for new MCP connections. Your MCP client opens a browser, you approve cubic access, and the client stores and refreshes tokens.

Existing API-key based MCP configs continue to work during the migration window, but new setup should not add an `Authorization` header or `cbk_` key.

## Install and log in

Cursor and VS Code support one-click MCP install links. For other clients, use the CLI or manual config steps below.

<Tabs>
  <Tab title="Cursor">
    1. Click [Add cubic to Cursor](https://cursor.com/en-US/install-mcp?name=cubic\&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vd3d3LmN1YmljLmRldi9hcGkvbWNwIn0%3D).
    2. Confirm the install in Cursor.
    3. Click **Connect** and complete OAuth.

    Manual fallback:

    1. Open Cursor **Settings**.
    2. Go to **Tools and MCP**.
    3. In MCP, use **Home MCP Servers** or your project-specific MCP section.
    4. Click **New MCP server**.
    5. Add this to the config and save:

    ```json theme={null}
    "cubic": {
      "type": "http",
      "url": "https://www.cubic.dev/api/mcp"
    }
    ```

    6. Click **Connect** and complete OAuth.
  </Tab>

  <Tab title="Cursor Agent">
    If Cursor IDE is installed, first click [Add cubic to Cursor](https://cursor.com/en-US/install-mcp?name=cubic\&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vd3d3LmN1YmljLmRldi9hcGkvbWNwIn0%3D). Cursor Agent reads the same MCP config.

    Manual fallback:

    Add cubic to `~/.cursor/mcp.json` or project `.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "cubic": {
          "type": "http",
          "url": "https://www.cubic.dev/api/mcp"
        }
      }
    }
    ```

    ```bash theme={null}
    cursor-agent mcp enable cubic
    cursor-agent mcp login cubic
    cursor-agent mcp list-tools cubic
    ```
  </Tab>

  <Tab title="VS Code">
    1. Click [Add cubic to VS Code](vscode:mcp/install?%7B%22name%22%3A%22cubic%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fwww.cubic.dev%2Fapi%2Fmcp%22%7D).
    2. Confirm the MCP install in VS Code.
    3. Complete the OAuth prompt.
    4. Run **MCP: List Servers** and confirm cubic is running.

    Manual fallback:

    1. Open the Command Palette.
    2. Run **MCP: Add Server**.
    3. Choose **HTTP**.
    4. Enter `https://www.cubic.dev/api/mcp`.
    5. Name it `cubic`.
  </Tab>

  <Tab title="Notion Custom Agent">
    Notion MCP connections are available on Notion Business and Enterprise plans. A workspace admin
    must enable custom MCP servers before an agent can connect to cubic.

    1. In Notion, ask a workspace admin to open **Settings** > **Notion AI** > **AI connectors** and enable **Custom MCP servers**.
    2. Open your Custom Agent's **Settings**.
    3. Go to **Tools & Access**.
    4. Click **Add connection** > **Custom MCP server**.
    5. Enter `https://www.cubic.dev/api/mcp`.
    6. Name the connection `cubic`.
    7. Choose OAuth and complete the cubic sign-in flow.
    8. Select which cubic tools the agent can use.

    Read tools such as `list_wikis`, `get_wiki_page`, `list_scans`, and `get_pr_issues` can run
    automatically if that matches your agent workflow.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http --scope user cubic https://www.cubic.dev/api/mcp
    ```

    Open Claude Code and run:

    ```text theme={null}
    /mcp
    ```

    Choose cubic and complete the browser OAuth flow.
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add cubic --url https://www.cubic.dev/api/mcp
    codex mcp login cubic
    codex mcp list
    ```
  </Tab>

  <Tab title="Gemini CLI">
    ```bash theme={null}
    gemini mcp add --transport http --scope user cubic https://www.cubic.dev/api/mcp
    ```

    Open Gemini CLI and run:

    ```text theme={null}
    /mcp auth cubic
    /mcp
    ```
  </Tab>

  <Tab title="OpenCode">
    Add this to `~/.config/opencode/opencode.json`:

    ```json theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "cubic": {
          "type": "remote",
          "url": "https://www.cubic.dev/api/mcp",
          "enabled": true
        }
      }
    }
    ```

    Then authenticate and verify:

    ```bash theme={null}
    opencode mcp auth cubic
    opencode mcp list
    ```
  </Tab>

  <Tab title="Droid">
    ```bash theme={null}
    droid mcp add cubic https://www.cubic.dev/api/mcp --type http
    ```

    Open Droid, run `/mcp`, choose cubic, and complete the browser OAuth flow.
  </Tab>

  <Tab title="Pi">
    Install cubic's Pi target:

    ```bash theme={null}
    npx @cubic-plugin/cubic-plugin install --to pi
    ```

    The installer writes Pi's MCP config to `~/.config/mcp/mcp.json`.

    Install the Pi MCP adapter if needed:

    Skip this step if `pi-mcp-adapter` is already installed.

    ```bash theme={null}
    pi install npm:pi-mcp-adapter
    ```

    Run Pi's guided setup:

    ```bash theme={null}
    pi-mcp-adapter init
    ```

    Confirm the MCP config contains:

    ```json theme={null}
    {
      "mcpServers": {
        "cubic": {
          "auth": "oauth",
          "url": "https://www.cubic.dev/api/mcp"
        }
      }
    }
    ```

    Open Pi and run:

    ```text theme={null}
    /mcp-auth cubic
    /mcp reconnect cubic
    ```
  </Tab>

  <Tab title="Generic">
    Use these details for any hosted MCP client that supports remote MCP OAuth and dynamic client
    registration.

    ```text theme={null}
    Transport: Streamable HTTP
    URL: https://www.cubic.dev/api/mcp
    Authentication: OAuth
    ```

    Your client should open a browser for cubic consent, store the returned tokens, and send the
    OAuth access token as a bearer token when calling the MCP endpoint.
  </Tab>
</Tabs>

## Available tools

| Tool                           | Description                                              |
| :----------------------------- | :------------------------------------------------------- |
| `list_wikis`                   | List all wikis you have access to                        |
| `list_wiki_pages`              | List all available wiki pages for a repository           |
| `get_wiki_page`                | Retrieve the content of a specific wiki page             |
| `list_scans`                   | List repository scan summaries                           |
| `get_scan`                     | List aggregated scan issues with filters and pagination  |
| `resolve_github_user_contacts` | Resolve GitHub usernames to email and Slack mentions     |
| `get_issue`                    | Get full issue details including code context            |
| `update_issue_status`          | Update a scan issue triage status with optional feedback |
| `list_learnings`               | List AI review learnings for a repository                |
| `get_learning`                 | Get full details of a specific learning                  |
| `get_pr_issues`                | Get all published issues for a pull request              |

## Common prompts

* "Show cubic review issues on PR #42 in acme/backend"
* "List wiki pages for acme/backend"
* "Show me the authentication system wiki page"
* "List codebase scan issues in acme/backend with severity at least 7"
* "Mark scan issue abc as false positive with feedback"
* "What review learnings apply to this repository?"

## Troubleshooting

<AccordionGroup>
  <Accordion title="Protected resource mismatch">
    Confirm your configured URL is exactly `https://www.cubic.dev/api/mcp`. Replacing `www.cubic.dev`
    with `cubic.dev` can cause OAuth clients to reject the connection.
  </Accordion>

  <Accordion title="401 Unauthorized errors">
    Run your client's login command again and complete the browser flow. If you still use a legacy
    API-key config, migrate it to OAuth.
  </Accordion>

  <Accordion title="MCP client not recognizing the server">
    Restart your AI client after updating configuration. For Cursor Agent, make sure the server is
    in `~/.cursor/mcp.json` or project `.cursor/mcp.json`, not only Cursor's `settings.json`.
  </Accordion>

  <Accordion title="No wiki pages found">
    Confirm the repository has an [AI Wiki generated](/wiki/ai-wiki), verify you have access to the
    repository's installation, and check that `owner` and `repo` match GitHub exactly.
  </Accordion>
</AccordionGroup>