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

# IDE Setup

> Configure Greptile MCP server in Claude Code, Claude Desktop, Cursor, VS Code, and Codex CLI

Configure the Greptile MCP server in your IDE to access code review tools and custom context.

<Note>
  **Prerequisite:** Get your API key from [app.greptile.com/settings/organization/api](https://app.greptile.com/settings/organization/api) (Settings > Organization > API Keys)
</Note>

## Setup by IDE

<Tabs>
  <Tab title="Claude Code (CLI)">
    <Steps>
      <Step title="Add Greptile MCP Server">
        Run the following command in your terminal:

        ```bash theme={}
        claude mcp add --transport http greptile https://api.greptile.com/mcp \
          --header "Authorization: Bearer YOUR_GREPTILE_API_KEY"
        ```

        Replace `YOUR_GREPTILE_API_KEY` with your actual API key.
      </Step>

      <Step title="Verify Installation">
        Check that the server was added:

        ```bash theme={}
        claude mcp list
        ```

        You should see:

        ```
        greptile: https://api.greptile.com/mcp (HTTP) - ✓ Connected
        ```
      </Step>

      <Step title="Start Using">
        Open Claude Code. The Greptile MCP tools are now available automatically.
      </Step>
    </Steps>

    ### Project-Level Configuration

    For team-shared configuration, create a `.mcp.json` file in your project root:

    ```json theme={}
    {
      "servers": {
        "greptile": {
          "transport": "http",
          "url": "https://api.greptile.com/mcp",
          "headers": {
            "Authorization": "Bearer ${GREPTILE_API_KEY}"
          }
        }
      }
    }
    ```

    Then set the environment variable:

    ```bash theme={}
    export GREPTILE_API_KEY=your-api-key-here
    ```
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Open Settings">
        Click the ⚙️ icon or press `Ctrl + Shift + J` (Windows/Linux) or `Cmd + Shift + J` (macOS).
      </Step>

      <Step title="Go to Tools & MCP">
        Click **Tools & MCP** in the left sidebar.

        <Frame>
          <img src="https://mintcdn.com/greptile/pPDrEYn7_-Bi_2Mg/images/cursor-tools-mcp.png?fit=max&auto=format&n=pPDrEYn7_-Bi_2Mg&q=85&s=e35ed3a88fd1275f6c5daac82cb0eba3" alt="Cursor Tools and MCP settings" width="272" height="197" data-path="images/cursor-tools-mcp.png" />
        </Frame>
      </Step>

      <Step title="Add Custom MCP">
        Click **Add Custom MCP**.

        <Frame>
          <img src="https://mintcdn.com/greptile/UPpVJVb6MO4m3Pv2/images/cursor-add-custom-mcp.png?fit=max&auto=format&n=UPpVJVb6MO4m3Pv2&q=85&s=193acc7fde5827f55d9c7fefd55bec7f" alt="Add custom MCP button" width="599" height="442" data-path="images/cursor-add-custom-mcp.png" />
        </Frame>
      </Step>

      <Step title="Configure mcp.json">
        Add the following configuration:

        ```json theme={}
        {
          "mcpServers": {
            "greptile": {
              "type": "http",
              "url": "https://api.greptile.com/mcp",
              "headers": {
                "Authorization": "Bearer YOUR_GREPTILE_API_KEY"
              }
            }
          }
        }
        ```

        Replace `YOUR_GREPTILE_API_KEY` with your actual API key. Save the file.
      </Step>

      <Step title="Verify Connection">
        Return to **Tools & MCP**. You should see Greptile with all 11 tools enabled.

        <Frame>
          <img src="https://mintcdn.com/greptile/pPDrEYn7_-Bi_2Mg/images/cursor-greptile-mcp-enabled.png?fit=max&auto=format&n=pPDrEYn7_-Bi_2Mg&q=85&s=627f418c9fa4c2381fe9cc644fa8e0aa" alt="Greptile MCP enabled in Cursor" width="599" height="440" data-path="images/cursor-greptile-mcp-enabled.png" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Desktop">
    Claude Desktop is a standalone application (separate from Claude Code CLI).

    <Steps>
      <Step title="Get Greptile API Key">
        Go to [app.greptile.com/settings/organization/api](https://app.greptile.com/settings/organization/api) (Settings > Organization > API Keys) and create an API key.

        <Frame>
          <img src="https://mintcdn.com/greptile/pPDrEYn7_-Bi_2Mg/images/greptile-api-keys.png?fit=max&auto=format&n=pPDrEYn7_-Bi_2Mg&q=85&s=1efa32f823264f1635a500e7edb5528a" alt="Greptile API Keys" width="258" height="440" data-path="images/greptile-api-keys.png" />
        </Frame>
      </Step>

      <Step title="Get GitHub Token">
        Generate a GitHub personal access token:

        1. Go to GitHub → **Settings** → **Developer settings**

        <Frame>
          <img src="https://mintcdn.com/greptile/pPDrEYn7_-Bi_2Mg/images/github-developer-settings.png?fit=max&auto=format&n=pPDrEYn7_-Bi_2Mg&q=85&s=aa89b343654d65e59bc6cce3a68ee9af" alt="GitHub Developer settings" width="356" height="642" data-path="images/github-developer-settings.png" />
        </Frame>

        2. Click **Personal access tokens** → **Tokens (classic)**

        <Frame>
          <img src="https://mintcdn.com/greptile/pPDrEYn7_-Bi_2Mg/images/github-p-a-token.png?fit=max&auto=format&n=pPDrEYn7_-Bi_2Mg&q=85&s=67793a05aa5ba44aeba4c25234027fac" alt="GitHub personal access token" width="1174" height="290" data-path="images/github-p-a-token.png" />
        </Frame>

        3. Click **Generate new token (classic)**

        <Frame>
          <img src="https://mintcdn.com/greptile/pPDrEYn7_-Bi_2Mg/images/generate-token-classic.png?fit=max&auto=format&n=pPDrEYn7_-Bi_2Mg&q=85&s=a734c6db39201ce38b42cfdd0f6915c4" alt="Generate new token" width="845" height="290" data-path="images/generate-token-classic.png" />
        </Frame>

        4. Set name, expiration, and required scopes, then click **Generate token**

        <Frame>
          <img src="https://mintcdn.com/greptile/pPDrEYn7_-Bi_2Mg/images/github-generate-personal-access-token.png?fit=max&auto=format&n=pPDrEYn7_-Bi_2Mg&q=85&s=32b6e1b15b450b6d4f6914ddfe84bf47" alt="Generate personal access token" width="823" height="559" data-path="images/github-generate-personal-access-token.png" />
        </Frame>

        5. Copy the token immediately (you won't see it again)
      </Step>

      <Step title="Open Claude Desktop Settings">
        Launch Claude Desktop → **File** → **Settings** → **Developer** tab → **Edit Config**

        <Frame>
          <img src="https://mintcdn.com/greptile/UPpVJVb6MO4m3Pv2/images/claude-edit-config.png?fit=max&auto=format&n=UPpVJVb6MO4m3Pv2&q=85&s=b87f120b8ffa08aabcf54b2012ec92ea" alt="Edit Claude config" width="1204" height="234" data-path="images/claude-edit-config.png" />
        </Frame>
      </Step>

      <Step title="Edit Configuration">
        Add to `claude_desktop_config.json`:

        ```json theme={}
        {
          "mcpServers": {
            "greptile": {
              "command": "npx",
              "args": ["greptile-mcp-server"],
              "env": {
                "GREPTILE_API_KEY": "your_greptile_api_key_here",
                "GITHUB_TOKEN": "your_github_token_here"
              }
            }
          }
        }
        ```

        Replace the placeholder values with your actual keys. Save and close.
      </Step>

      <Step title="Restart Claude Desktop">
        Close and relaunch Claude Desktop.
      </Step>

      <Step title="Verify Installation">
        Return to **Developer** tab. You should see `greptile` listed as a running MCP server.

        <Frame>
          <img src="https://mintcdn.com/greptile/UPpVJVb6MO4m3Pv2/images/claude-local-mcp-servers.png?fit=max&auto=format&n=UPpVJVb6MO4m3Pv2&q=85&s=55ea8fe98ae56448f3ba982dd23c1e2a" alt="Claude Greptile MCP server" width="1204" height="638" data-path="images/claude-local-mcp-servers.png" />
        </Frame>

        Open a new chat and click the hammer icon to see available Greptile tools.

        <Frame>
          <img src="https://mintcdn.com/greptile/UPpVJVb6MO4m3Pv2/images/claude-greptile-tools.png?fit=max&auto=format&n=UPpVJVb6MO4m3Pv2&q=85&s=2d6818de376a47dbe2f79bd28c36c23c" alt="Claude Greptile tools" width="780" height="443" data-path="images/claude-greptile-tools.png" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="VS Code">
    <Steps>
      <Step title="Open Command Palette">
        Press `Ctrl + Shift + P` (Windows/Linux) or `Cmd + Shift + P` (macOS).
      </Step>

      <Step title="Add MCP Server">
        Type `MCP` and select **MCP: Add Server**.

        <Frame>
          <img src="https://mintcdn.com/greptile/sJeefWhR1h6iqsSa/images/vscode-mcp-add.png?fit=max&auto=format&n=sJeefWhR1h6iqsSa&q=85&s=d4dc25696fa020f32d381229e808a33b" alt="Add MCP Server in VS Code" width="600" height="281" data-path="images/vscode-mcp-add.png" />
        </Frame>
      </Step>

      <Step title="Select HTTP Type">
        Choose **HTTP (HTTP or Server-Sent-Events)**.

        <Frame>
          <img src="https://mintcdn.com/greptile/sJeefWhR1h6iqsSa/images/vscode-mcp-type.png?fit=max&auto=format&n=sJeefWhR1h6iqsSa&q=85&s=5384a6058f8c4e93f9dfc0996410d9e9" alt="Select HTTP type" width="600" height="112" data-path="images/vscode-mcp-type.png" />
        </Frame>
      </Step>

      <Step title="Enter URL">
        Enter: `https://api.greptile.com/mcp`
      </Step>

      <Step title="Select Scope">
        Choose **Global** or **Workspace**.

        <Frame>
          <img src="https://mintcdn.com/greptile/sJeefWhR1h6iqsSa/images/vscode-mcp-scope.png?fit=max&auto=format&n=sJeefWhR1h6iqsSa&q=85&s=4b0caed12d7183c975e3fb4a353fc0d8" alt="Select scope" width="600" height="112" data-path="images/vscode-mcp-scope.png" />
        </Frame>
      </Step>

      <Step title="Add Authorization Header">
        An `mcp.json` file will be created. Add the Authorization header:

        ```json theme={}
        {
          "servers": {
            "greptile": {
              "url": "https://api.greptile.com/mcp",
              "type": "http",
              "headers": {
                "Authorization": "Bearer YOUR_GREPTILE_API_KEY"
              }
            }
          }
        }
        ```

        Replace `YOUR_GREPTILE_API_KEY` with your actual API key.
      </Step>

      <Step title="Verify Installation">
        Run **MCP: List Servers** from Command Palette. You should see Greptile with status **Running**.

        <Frame>
          <img src="https://mintcdn.com/greptile/sJeefWhR1h6iqsSa/images/vscode-mcp-status.png?fit=max&auto=format&n=sJeefWhR1h6iqsSa&q=85&s=f307621c9cc4b023773547e48b9a6056" alt="MCP server status" width="600" height="112" data-path="images/vscode-mcp-status.png" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Codex (CLI)">
    <Steps>
      <Step title="Add Greptile MCP Server">
        Run the following command in your terminal:

        ```bash theme={}
        codex mcp add greptile --url https://api.greptile.com/mcp \
          --bearer-token-env-var GREPTILE_API_KEY
        ```

        Then set your API key as an environment variable:

        ```bash theme={}
        export GREPTILE_API_KEY=your-api-key-here
        ```
      </Step>

      <Step title="Verify Installation">
        Check that the server was added:

        ```bash theme={}
        codex mcp list
        ```

        You should see:

        ```
        Name      Url                           Bearer Token Env Var  Status   Auth
        greptile  https://api.greptile.com/mcp  GREPTILE_API_KEY      enabled  Bearer token
        ```
      </Step>

      <Step title="Start Using">
        Open Codex. The Greptile MCP tools are available automatically.
      </Step>
    </Steps>

    ### Project-Level Configuration

    For team-shared configuration, create a `.codex/config.toml` file in your project root:

    ```toml theme={}
    [mcp_servers.greptile]
    url = "https://api.greptile.com/mcp"
    bearer_token_env_var = "GREPTILE_API_KEY"
    ```

    Then set the environment variable:

    ```bash theme={}
    export GREPTILE_API_KEY=your-api-key-here
    ```
  </Tab>
</Tabs>

## Verify Connection

Test your setup with curl:

```bash theme={}
curl -X POST https://api.greptile.com/mcp \
  -H "Authorization: Bearer YOUR_GREPTILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'
```

Expected response:

```json theme={}
{"jsonrpc":"2.0","id":1,"result":{}}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Server shows as disconnected">
    **Check:**

    * API key is correct and hasn't expired
    * URL is exactly `https://api.greptile.com/mcp`
    * Authorization header format: `Bearer YOUR_API_KEY` (with Bearer prefix)

    **Fix:** Restart your IDE after making configuration changes.
  </Accordion>

  <Accordion title="Authentication failed">
    **Verify:**

    * API key was copied without extra spaces
    * Your account has access to the repositories you're querying
    * API key hasn't been revoked

    **Test:** Use the curl command in the "Verify Connection" section above to verify your API key works.
  </Accordion>

  <Accordion title="No tools available">
    **Solutions:**

    1. Restart your IDE completely
    2. Check server shows "Connected" or "Running" status
    3. Verify MCP is enabled in IDE settings
  </Accordion>

  <Accordion title="Tools return empty results">
    **Check:**

    * You have repositories indexed with Greptile
    * Your API key has access to those repositories
    * There are actual Greptile comments on your PRs
  </Accordion>

  <Accordion title="Claude Desktop: GitHub token validation failed">
    **Check:**

    * Token hasn't expired
    * Token was copied without extra spaces or missing characters
    * Token has required scopes for the repositories you're accessing

    **Fix:** Generate a new token at [github.com/settings/tokens](https://github.com/settings/tokens)
  </Accordion>

  <Accordion title="Claude Desktop: Failed to start server">
    **Check:**

    * Both `GREPTILE_API_KEY` and `GITHUB_TOKEN` are set in the config
    * The `greptile-mcp-server` package can be accessed via npx

    **Fix:** Verify your config file syntax is valid JSON
  </Accordion>
</AccordionGroup>

## Configuration File Locations

| IDE            | Config File                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------ |
| Claude Code    | `~/.mcp.json` or project `.mcp.json`                                                                   |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)                              |
| Cursor         | Set via UI (Settings → Tools & MCP)                                                                    |
| VS Code        | `~/.config/Code/User/mcp.json` (Linux)<br />`~/Library/Application Support/Code/User/mcp.json` (macOS) |
| Codex CLI      | `~/.codex/config.toml` or project `.codex/config.toml`                                                 |

## Next Steps

<CardGroup cols={2}>
  <Card title="Auto-Fix Workflow" icon="wand-magic-sparkles" href="/docs/mcp/auto-fix">
    Learn to resolve Greptile comments from your IDE
  </Card>

  <Card title="Tools Reference" icon="book" href="/docs/mcp/tools">
    Complete API documentation for all 11 tools
  </Card>
</CardGroup>