diff --git a/cspell-allow-list.txt b/cspell-allow-list.txt index ba469f385..1a1eb74f2 100644 --- a/cspell-allow-list.txt +++ b/cspell-allow-list.txt @@ -319,6 +319,7 @@ Marino maxage maxmemory maxpages +mcps megarepo Memorystore Menlo diff --git a/docs/api/mcp/client-integrations.mdx b/docs/api/mcp/client-integrations.mdx index 85ee5b377..1a7d2611f 100644 --- a/docs/api/mcp/client-integrations.mdx +++ b/docs/api/mcp/client-integrations.mdx @@ -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: @@ -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`. - - - `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. - +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 @@ -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 { @@ -106,33 +99,76 @@ To authenticate with a Sourcegraph access token instead, set `SOURCEGRAPH_ACCESS } ``` -### Copilot + + + + +### 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: @@ -140,12 +176,14 @@ To authenticate with a Sourcegraph access token instead, disable OAuth and add a { "$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}" + } } } } @@ -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 @@ -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 { @@ -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`. + + + +### 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 @@ -206,94 +277,48 @@ You can add the Sourcegraph MCP server to Google Gemini Code Assist by configuri ``` - 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. 3. Save the configuration file. 4. Restart Gemini Code Assist to apply the new configuration. -### VS Code + -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": [] - } - ``` - - - Replace `sourcegraph.example.com` with your Sourcegraph instance - URL and `YOUR_ACCESS_TOKEN` with your access token. - - -#### 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. - - Replace `sourcegraph.example.com` with your Sourcegraph instance - URL and `YOUR_ACCESS_TOKEN` with your access token. - +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" + } + } + } +} +``` diff --git a/docs/api/mcp/index.mdx b/docs/api/mcp/index.mdx index 580cea62c..b33284922 100644 --- a/docs/api/mcp/index.mdx +++ b/docs/api/mcp/index.mdx @@ -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. Clients that use Dynamic Client Registration (for example, Claude Code with