Skip to content

docs/mcp: Update client setup instructions #2166

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
eseliger wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs/mcp: Update client setup instructions #2166

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions cspell-allow-list.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -319,6 +319,7 @@ Marino
maxage
maxmemory
maxpages
mcps
megarepo
Memorystore
Menlo
Expand Down
249 changes: 137 additions & 112 deletions docs/api/mcp/client-integrations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,23 +13,24 @@
- [Claude Code](#claude-code)
- [Codex](#codex)
- [Cursor](#cursor)
- [Copilot](#copilot)
- [GitHub Copilot](#github-copilot)
- [OpenCode](#opencode)
- [Amp](#amp)
- [Google Antigravity](#google-antigravity)
- [Google Gemini Code Assist](#google-gemini-code-assist)
- [VS Code](#vs-code)
- [Antigravity](#antigravity)
- [Windsurf](#windsurf)
- [Devin Desktop](#devin-desktop)

In all examples, replace `sourcegraph.example.com` with your Sourcegraph instance URL. For Claude Code, Cursor, GitHub Copilot, OpenCode, and Amp access-token authentication, set `SOURCEGRAPH_ACCESS_TOKEN` in the client's environment. In other access-token examples, replace `YOUR_ACCESS_TOKEN` with a [Sourcegraph access token](/cli/how-tos/creating-an-access-token).

### Claude Code

Add the Sourcegraph MCP server to [Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp):
Add the Sourcegraph MCP server to [Claude Code](https://code.claude.com/docs/en/mcp) for all your projects:

```bash
claude mcp add --transport http sourcegraph https://sourcegraph.example.com/.api/mcp
claude mcp add --transport http --scope user sourcegraph https://sourcegraph.example.com/.api/mcp
```

Then run `/mcp` in Claude Code and follow the browser authentication flow.
Then run `claude mcp login sourcegraph`, or run `/mcp` in Claude Code, and follow the browser authentication flow. Without `--scope user`, Claude Code adds the server only for the current project.

To share an access-token configuration with a project, set `SOURCEGRAPH_ACCESS_TOKEN` in your environment and add the following to `.mcp.json` in the project root:

Expand Down Expand Up @@ -58,22 +59,14 @@ Locally scoped servers take precedence over project-scoped servers with the same

### Codex

Add the Sourcegraph MCP server to [Codex](https://learn.chatgpt.com/docs/extend/mcp) by adding the following to `~/.codex/config.toml`, or to `.codex/config.toml` for a trusted project:
Add the Sourcegraph MCP server to [Codex](https://learn.chatgpt.com/docs/extend/mcp) by adding the following to `~/.codex/config.toml`, or to `.codex/config.toml` for a trusted project. The Codex CLI, IDE extension, and ChatGPT desktop app share this configuration.

```toml
[mcp_servers.sourcegraph]
url = "https://sourcegraph.example.com/.api/mcp"
scopes = ["mcp"]
```

Then authenticate with `codex mcp login sourcegraph`.

<Callout type="note">
`scopes = ["mcp"]` is required. Without it, Codex's OAuth login fails with
an `invalid_scope` error because Sourcegraph's MCP endpoints require the
`mcp` scope. See [Troubleshooting: `invalid_scope` error during
OAuth](/api/mcp#invalid_scope-error-during-oauth) for details.
</Callout>
Then authenticate with `codex mcp login sourcegraph`. If sign-in fails with an `invalid_scope` error, see [Troubleshooting](/api/mcp#invalid_scope-error-during-oauth).

### Cursor

Expand All @@ -89,9 +82,9 @@ Add the following to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` for a projec
}
```

Enable the server from **Cursor Settings > Tools & MCP** and follow the OAuth prompt. See [Cursor's MCP documentation](https://cursor.com/docs/mcp) for more information.
Enable the server from Cursor's **Customize** page and follow the OAuth prompt. See [Cursor's MCP documentation](https://cursor.com/docs/mcp) for more information.

To authenticate with a Sourcegraph access token instead, set `SOURCEGRAPH_ACCESS_TOKEN` in Cursor's environment and add an authorization header:
To authenticate with a Sourcegraph access token instead, add an authorization header:

```json
{
Expand All @@ -106,46 +99,91 @@ To authenticate with a Sourcegraph access token instead, set `SOURCEGRAPH_ACCESS
}
```

### Copilot
<span id="copilot"> </span>

<span id="vs-code"> </span>

### GitHub Copilot

Add the Sourcegraph MCP server to [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers):
[GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) and Copilot in VS Code read the same MCP configuration file, `~/.copilot/mcp-config.json`. Add the Sourcegraph MCP server with the Copilot CLI:

```bash
copilot mcp add --transport http sourcegraph https://sourcegraph.example.com/.api/mcp
```

Then run `/mcp auth sourcegraph` and follow the authentication flow.
Or add the following to `~/.copilot/mcp-config.json`:

```json
{
"mcpServers": {
"sourcegraph": {
"type": "http",
"url": "https://sourcegraph.example.com/.api/mcp",
"tools": ["*"]
}
}
}
```

To authenticate, run `/mcp auth sourcegraph` in Copilot CLI, or select **Authenticate** on the server in VS Code. In VS Code, you can also run **Chat: Open Customizations**, select **MCP Servers** > **Add Server**, choose **HTTP**, and save the server to **Global** > **Copilot Global** to write the same file. See [VS Code's MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers) for more information.

To authenticate with a Sourcegraph access token instead, add an authorization header:

```json
{
"mcpServers": {
"sourcegraph": {
"type": "http",
"url": "https://sourcegraph.example.com/.api/mcp",
"tools": ["*"],
"headers": {
"Authorization": "token ${SOURCEGRAPH_ACCESS_TOKEN}"
}
}
}
}
```

### OpenCode

Add the following to `~/.config/opencode/opencode.json` for a global configuration, or to `opencode.json` in a project root for a project-specific configuration:
Add the Sourcegraph MCP server to [OpenCode](https://opencode.ai/docs/mcp-servers/) for all your projects:

```bash
opencode mcp add sourcegraph --global --url https://sourcegraph.example.com/.api/mcp
```

Without `--global`, OpenCode adds the server to the current project's configuration. You can also add the following to `~/.config/opencode/opencode.json`, or to `opencode.json` in a project root:

```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"sourcegraph": {
"type": "remote",
"url": "https://sourcegraph.example.com/.api/mcp"
"servers": {
"sourcegraph": {
"type": "remote",
"url": "https://sourcegraph.example.com/.api/mcp"
}
}
}
}
```

Then authenticate with `opencode mcp auth sourcegraph`. See [OpenCode's MCP documentation](https://opencode.ai/docs/mcp-servers/) for more information.
Then authenticate with `opencode mcp auth sourcegraph`, or run `/mcps` in OpenCode and select the server.

To authenticate with a Sourcegraph access token instead, disable OAuth and add an authorization header:

```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"sourcegraph": {
"type": "remote",
"url": "https://sourcegraph.example.com/.api/mcp",
"oauth": false,
"headers": {
"Authorization": "token {env:SOURCEGRAPH_ACCESS_TOKEN}"
"servers": {
"sourcegraph": {
"type": "remote",
"url": "https://sourcegraph.example.com/.api/mcp",
"oauth": false,
"headers": {
"Authorization": "token {env:SOURCEGRAPH_ACCESS_TOKEN}"
}
}
}
}
Expand All @@ -154,7 +192,7 @@ To authenticate with a Sourcegraph access token instead, disable OAuth and add a

### Amp

Add the Sourcegraph MCP server to [Amp](https://ampcode.com/manual#mcp):
Add the Sourcegraph MCP server to [Amp](https://ampcode.com/docs/customize/mcp):

```bash
amp mcp add sourcegraph https://sourcegraph.example.com/.api/mcp
Expand All @@ -168,7 +206,7 @@ To authenticate with a Sourcegraph access token instead, add an authorization he
amp mcp add sourcegraph --header "Authorization=token $SOURCEGRAPH_ACCESS_TOKEN" https://sourcegraph.example.com/.api/mcp
```

You can also configure the access-token connection in VS Code's `settings.json`:
You can also configure the access-token connection in Amp's settings file, `~/.config/amp/settings.json`:

```json
{
Expand All @@ -183,7 +221,40 @@ You can also configure the access-token connection in VS Code's `settings.json`:
}
```

In all examples, replace `sourcegraph.example.com` with your Sourcegraph instance URL. For Claude Code, Cursor, OpenCode, and Amp access-token authentication, set `SOURCEGRAPH_ACCESS_TOKEN` in the client's environment. In other access-token examples, replace `YOUR_ACCESS_TOKEN` with a [Sourcegraph access token](/cli/how-tos/creating-an-access-token).
These commands and settings configure Amp on your computer. Amp threads that run in orbs don't read them. To use Sourcegraph in orbs, add the server in your Amp [MCP server settings](https://ampcode.com/settings/mcp-servers), or with `amp mcp remote --personal add sourcegraph https://sourcegraph.example.com/.api/mcp`.

<span id="antigravity"> </span>

### Google Antigravity

The [Antigravity](https://antigravity.google/docs/mcp) app, IDE, and CLI read MCP servers from an `mcp_config.json` file. Antigravity CLI uses `~/.gemini/config/mcp_config.json` for all projects and `.agents/mcp_config.json` for a workspace. In the Antigravity app, click **Copy Config File Path** in the MCP servers section to find its file. Add the following:

```json
{
"mcpServers": {
"sourcegraph": {
"serverUrl": "https://sourcegraph.example.com/.api/mcp"
}
}
}
```

Then click **Authenticate** next to the server in **Customizations** and complete the browser authentication flow.

To authenticate with a Sourcegraph access token instead, add an authorization header:

```json
{
"mcpServers": {
"sourcegraph": {
"serverUrl": "https://sourcegraph.example.com/.api/mcp",
"headers": {
"Authorization": "token YOUR_ACCESS_TOKEN"
}
}
}
}
```

### Google Gemini Code Assist

Expand All @@ -206,94 +277,48 @@ You can add the Sourcegraph MCP server to Google Gemini Code Assist by configuri
```

<Callout type="info">
Replace `sourcegraph.example.com` with your Sourcegraph instance
URL and `YOUR_ACCESS_TOKEN` with your access token.
Replace `sourcegraph.example.com` with your Sourcegraph instance URL and
`YOUR_ACCESS_TOKEN` with your access token.
</Callout>

3. Save the configuration file.
4. Restart Gemini Code Assist to apply the new configuration.

### VS Code
<span id="windsurf"> </span>

You can add the Sourcegraph MCP server to VS Code in one of two ways:
### Devin Desktop

#### Option 1: `code` CLI

1. Run the following command to add the MCP server to the global configuration
Devin Desktop, formerly Windsurf, shares its MCP configuration with the [Devin CLI](https://docs.devin.ai/cli/extensibility/mcp/configuration). Add the Sourcegraph MCP server for all your projects:

```bash
code --add-mcp "{ \"name\": \"sourcegraph\", \"type\": \"remote\", \"url\": \"https://sourcegraph.example.com/.api/mcp\" }"
devin mcp add -s user sourcegraph https://sourcegraph.example.com/.api/mcp
```

2. Launch or restart VS Code to apply the new configuration.

#### Option 2: VSCode `mcp.json`

1. Create `.vscode/mcp.json` in your project.
2. Add the following configuration:

```json
{
"servers": {
"sourcegraph": {
"type": "http",
"url": "https://sourcegraph.example.com/.api/mcp"
}
},
"inputs": []
}
```

3. Save the configuration file.
4. Restart VS Code to apply the new configuration.

#### Antigravity
Or add the following to `~/.config/devin/mcp_config.json` (`%APPDATA%\devin\mcp_config.json` on Windows):

1. Create ⁠`.vscode/mcp.json` (Antigravity uses `.vscode` for configs) in your project.
2. Add the following:

```json
{
"servers": {
"sourcegraph": {
"url": "https://sourcegraph.example.com/.api/mcp",
"type": "http",
"headers": {
"Authorization": "token YOUR_ACCESS_TOKEN"
}
}
},
"inputs": []
}
```

<Callout type="info">
Replace `sourcegraph.example.com` with your Sourcegraph instance
URL and `YOUR_ACCESS_TOKEN` with your access token.
</Callout>

#### Windsurf

1. Create ⁠`~/.codeium/windsurf/mcp_config.json`.
2. Add the following:
```json
{
"mcpServers": {
"sourcegraph": {
"url": "https://sourcegraph.example.com/.api/mcp"
}
}
}
```

```json
{
"mcpServers": {
"sourcegraph": {
"serverUrl": "https://sourcegraph.example.com/.api/mcp",
"headers": {
"Authorization": "token YOUR_ACCESS_TOKEN",
"Content-Type": "application/json"
}
}
}
}
```
Then run `devin mcp login sourcegraph`, or click **Authenticate** on the server in Devin Desktop.

<Callout type="info">
Replace `sourcegraph.example.com` with your Sourcegraph instance
URL and `YOUR_ACCESS_TOKEN` with your access token.
</Callout>
To authenticate with a Sourcegraph access token instead, add an authorization header:

3. Save the configuration file.
```json
{
"mcpServers": {
"sourcegraph": {
"url": "https://sourcegraph.example.com/.api/mcp",
"headers": {
"Authorization": "token YOUR_ACCESS_TOKEN"
}
}
}
}
```
2 changes: 1 addition & 1 deletion docs/api/mcp/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -470,7 +470,7 @@ If your MCP client's OAuth login fails with an `invalid_scope` error when connec

To fix this, pin `scopes = ["mcp"]` in your client's OAuth configuration so the client requests only the `mcp` scope during the OAuth flow.

For OpenAI Codex specifically, set `scopes = ["mcp"]` in your `config.toml`. See the [Codex](/api/mcp/client-integrations#codex) section on the client integrations page for the full configuration.
For OpenAI Codex, add `scopes = ["mcp"]` under `[mcp_servers.sourcegraph]` in your `config.toml`, then run `codex mcp login sourcegraph` again.

<Callout type="info">
Clients that use Dynamic Client Registration (for example, Claude Code with
Expand Down
Loading