IDE Setup

Greptile MCP supports OAuth and organization API keys.

Use OAuth for interactive IDE sessions. Use an API key for automation or clients that cannot complete a browser sign-in.

OAuth requires a server entry without a static Authorization header or bearer-token setting. Remove either credential before starting OAuth. Other headers, including X-Greptile-Tenant, can be used with OAuth.

OAuth setup

OAuth signs you in through your browser. You do not need to create an API key or register an OAuth client.

Cursor
Claude Code
VS Code
Codex

Open MCP settings

Open Customize and select MCPs.

Add Greptile

Add this configuration to project-level .cursor/mcp.json or user-level ~/.cursor/mcp.json:

{
  "mcpServers": {
    "greptile": {
      "url": "https://api.greptile.com/mcp"
    }
  }
}

Ask Cursor:

List my Greptile custom context rules.

On the first protected tool call, follow the browser prompt to sign in.

Verify the connection

Run the same prompt again. A successful list_custom_context result confirms authentication. Seeing Greptile’s tools in settings confirms discovery, but not authentication.

Add Greptile

Run:

claude mcp add --transport http greptile https://api.greptile.com/mcp

Start OAuth explicitly:

claude mcp login greptile

Alternatively, open Claude Code, run /mcp, select greptile, and choose Authenticate.For an SSH or headless session, run claude mcp login greptile --no-browser. Open the printed URL, then paste the final redirect URL into the terminal when prompted.

Verify the connection

Run:

claude mcp list

Then ask Claude:

List my Greptile custom context rules.

A successful result confirms authentication.

Shared project configuration

To share the server definition with your team, create .mcp.json in the project root. Each developer authenticates separately.

{
  "mcpServers": {
    "greptile": {
      "type": "http",
      "url": "https://api.greptile.com/mcp"
    }
  }
}

Add an MCP server

Open the Command Palette and run MCP: Add Server.

Enter the server URL

Choose HTTP, enter https://api.greptile.com/mcp, then select Global or Workspace.

In chat, ask VS Code:

List my Greptile custom context rules.

On the first protected tool call, follow the browser prompt to sign in.

Verify the connection

Run the same prompt again. A successful list_custom_context result confirms authentication. A Running status in MCP: List Servers confirms discovery, but not authentication.

The equivalent mcp.json entry has no static authorization header:

{
  "servers": {
    "greptile": {
      "type": "http",
      "url": "https://api.greptile.com/mcp"
    }
  }
}

Add Greptile

Run:

codex mcp add greptile --url https://api.greptile.com/mcp

Start OAuth explicitly:

codex mcp login greptile

In the Codex IDE extension, open MCP servers, select Greptile, then select Authenticate.

Verify the connection

Run:

codex mcp list

Then ask Codex:

List my Greptile custom context rules.

A successful result confirms authentication.

Shared project configuration

Add this entry without a static authorization credential to .codex/config.toml. Each developer runs codex mcp login greptile separately.

[mcp_servers.greptile]
url = "https://api.greptile.com/mcp"

Multiple organizations

Accounts with more than one Greptile organization get tenant_required. The error lists every organization you belong to, by name and id. Set X-Greptile-Tenant to your organization’s handle or id. The handle is the first path segment of every Greptile URL, for example app.greptile.com/your-handle. The id is the one in the error. Any member can read the handle from the URL. Only an admin can change it. See Change organization handle. If the handle changes, update the header. The id never changes. This header routes requests. It does not authenticate them and works with OAuth.

Cursor
Claude Code
VS Code
Codex

Add the header to the OAuth server entry:

{
  "mcpServers": {
    "greptile": {
      "url": "https://api.greptile.com/mcp",
      "headers": {
        "X-Greptile-Tenant": "YOUR_ORGANIZATION_HANDLE"
      }
    }
  }
}

If you used the local configuration above, replace that entry with one that includes the routing header. Then sign in again:

claude mcp remove --scope local greptile
claude mcp add --transport http greptile https://api.greptile.com/mcp \
  --header "X-Greptile-Tenant: YOUR_ORGANIZATION_HANDLE"
claude mcp login greptile

If you use shared configuration, edit the existing Greptile entry in .mcp.json instead. Each developer authenticates separately.

{
  "mcpServers": {
    "greptile": {
      "type": "http",
      "url": "https://api.greptile.com/mcp",
      "headers": {
        "X-Greptile-Tenant": "YOUR_ORGANIZATION_HANDLE"
      }
    }
  }
}

Add the header to the OAuth server entry:

{
  "servers": {
    "greptile": {
      "type": "http",
      "url": "https://api.greptile.com/mcp",
      "headers": {
        "X-Greptile-Tenant": "YOUR_ORGANIZATION_HANDLE"
      }
    }
  }
}

Add the routing header to .codex/config.toml, then sign in:

[mcp_servers.greptile]
url = "https://api.greptile.com/mcp"
http_headers = { "X-Greptile-Tenant" = "YOUR_ORGANIZATION_HANDLE" }

codex mcp login greptile

Codex reads MCP configuration at startup. Restart Codex after editing config.toml.

If your client cannot set headers, pass the same handle or id as the organization argument on any tool call. If you set both, reads follow the argument. Tool calls that write are rejected when the two name different organizations.

API key setup

Create an API key in Settings > Organization > API Keys, then configure your client below.

Do not paste an API key directly into a configuration file that can be committed. Use an environment variable or a password input.

Cursor
Claude Code
VS Code
Codex

On macOS or Linux, open the Command Palette and run Shell Command: Install ‘cursor’ command in PATH once. Then set the key and launch Cursor from the same terminal so the app inherits it:

export GREPTILE_API_KEY="your-api-key-here"
cursor .

Then add this configuration to project-level .cursor/mcp.json or user-level ~/.cursor/mcp.json:

{
  "mcpServers": {
    "greptile": {
      "url": "https://api.greptile.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:GREPTILE_API_KEY}"
      }
    }
  }
}

Save the file, then call a Greptile tool to verify authentication.

Reference GREPTILE_API_KEY in project .mcp.json. Do not commit the key:

{
  "mcpServers": {
    "greptile": {
      "type": "http",
      "url": "https://api.greptile.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GREPTILE_API_KEY}"
      }
    }
  }
}

Set the variable before starting Claude Code. Each developer sets their own value:

export GREPTILE_API_KEY="your-api-key-here"

Configure a password input so VS Code prompts for the key without storing it in mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "greptile-api-key",
      "description": "Greptile API key",
      "password": true
    }
  ],
  "servers": {
    "greptile": {
      "type": "http",
      "url": "https://api.greptile.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:greptile-api-key}"
      }
    }
  }
}

Start the server, enter the key when prompted, then call a Greptile tool to verify authentication.

Store the key in an environment variable, then add the server:

export GREPTILE_API_KEY="your-api-key-here"
codex mcp add greptile --url https://api.greptile.com/mcp \
  --bearer-token-env-var GREPTILE_API_KEY

For shared configuration, create .codex/config.toml:

[mcp_servers.greptile]
url = "https://api.greptile.com/mcp"
bearer_token_env_var = "GREPTILE_API_KEY"

Verify API key authentication

Call an authenticated tool directly:

export GREPTILE_API_KEY="your-api-key-here"
curl -i -X POST https://api.greptile.com/mcp \
  -H "Authorization: Bearer $GREPTILE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_custom_context","arguments":{"limit":1}}}'

A valid key returns a JSON-RPC result. An invalid or revoked key returns 401 Unauthorized.

Troubleshooting

The server connects, but tool calls are unauthorized

MCP discovery can succeed before authentication is complete. Run claude mcp login greptile or codex mcp login greptile. In Cursor or VS Code, invoke a protected tool such as list_custom_context, then finish the OAuth prompt.

OAuth is not offered

Remove any static Authorization header or bearer-token setting from the Greptile server entry, restart the client, then invoke a protected tool such as list_custom_context. The resulting authentication challenge starts OAuth discovery.

The OAuth browser does not open

Claude Code users can run claude mcp login greptile --no-browser and open the printed URL manually. In Cursor or VS Code, invoke a protected tool such as list_custom_context to trigger authentication.

Tool calls return tenant_required

Your account belongs to multiple Greptile organizations. See Multiple organizations to find your organization’s handle or id and set it as the X-Greptile-Tenant header. Agents can pass it as the organization argument instead.

API key authentication fails

Confirm that the key has no extra spaces, has not been revoked, and belongs to an organization that can access the requested repositories. Use the authenticated curl request above to test it.

No tools are available

Restart the client, confirm Greptile is enabled, and check that the server URL is exactly https://api.greptile.com/mcp.

Tools return empty results

Confirm that your organization has repositories indexed in Greptile and that your user or API key can access them.

Configuration file locations

Client	Configuration file
Claude Code	`~/.claude.json` or project `.mcp.json`
Cursor	`~/.cursor/mcp.json` or project `.cursor/mcp.json`
VS Code	User-profile `mcp.json` or project `.vscode/mcp.json`
Codex	`~/.codex/config.toml` or project `.codex/config.toml`

OAuth setup

Shared project configuration

Shared project configuration

Multiple organizations

API key setup

Verify API key authentication

Troubleshooting

Configuration file locations

Next steps

Auto-Fix Workflow

Tools Reference

​OAuth setup

​Shared project configuration

​Shared project configuration

​Multiple organizations

​API key setup

​Verify API key authentication

​Troubleshooting

​Configuration file locations

​Next steps

Auto-Fix Workflow

Tools Reference

OAuth setup

Shared project configuration

Shared project configuration

Multiple organizations

API key setup

Verify API key authentication

Troubleshooting

Configuration file locations

Next steps