diff --git a/docs/api/mcp/client-integrations.mdx b/docs/api/mcp/client-integrations.mdx index 5daaf0323..ae63571c6 100644 --- a/docs/api/mcp/client-integrations.mdx +++ b/docs/api/mcp/client-integrations.mdx @@ -10,107 +10,180 @@ ## Supported Clients -- [Amp](#amp) - [Claude Code](#claude-code) +- [Codex](#codex) +- [Cursor](#cursor) +- [Copilot](#copilot) +- [OpenCode](#opencode) +- [Amp](#amp) - [Google Gemini Code Assist](#google-gemini-code-assist) - [VS Code](#vs-code) - - [Cursor](#cursor) - [Antigravity](#antigravity) - [Windsurf](#windsurf) -- [OpenCode](#opencode) -- [Codex](#codex) -### Amp +### Claude Code -You can add the Sourcegraph MCP server to [Amp](https://ampcode.com) in two ways: +Add the Sourcegraph MCP server to [Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp): -#### Option 1: VSCode settings.json +```bash +claude mcp add --transport http sourcegraph https://sourcegraph.example.com/.api/mcp +``` -1. Open VSCode's `settings.json` file. -2. Add the following configuration: +Then run `/mcp` in Claude Code and follow the browser authentication flow. + +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: + +```json +{ + "mcpServers": { + "sourcegraph": { + "type": "http", + "url": "https://sourcegraph.example.com/.api/mcp", + "headers": { + "Authorization": "token ${SOURCEGRAPH_ACCESS_TOKEN}" + } + } + } +} +``` - ```json - { - "amp.mcpServers": { - "sourcegraph": { - "url": "https://your-sourcegraph-instance.com/.api/mcp", - "headers": { - "Authorization": "token YOUR_ACCESS_TOKEN" - } - } - } - } - ``` +You can also add an access-token configuration for the current project with the CLI: - - Replace `your-sourcegraph-instance.com` with your Sourcegraph instance - URL and `YOUR_ACCESS_TOKEN` with your access token. - +```bash +claude mcp add --transport http sourcegraph https://sourcegraph.example.com/.api/mcp \ + --header "Authorization: token $SOURCEGRAPH_ACCESS_TOKEN" +``` -3. Save the configuration file. -4. Restart VS Code to apply the new configuration. +Locally scoped servers take precedence over project-scoped servers with the same name. -#### Option 2: Amp CLI +### Codex -Run the following command in your terminal: +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: -```bash -amp mcp add sourcegraph --header "Authorization=token YOUR_ACCESS_TOKEN" https://sourcegraph.sourcegraph.com/.api/mcp +```toml +[mcp_servers.sourcegraph] +url = "https://sourcegraph.example.com/.api/mcp" +scopes = ["mcp"] ``` - - Replace `sourcegraph.sourcegraph.com` with your Sourcegraph instance URL and - set `YOUR_ACCESS_TOKEN` environment variable to your access token. +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. -### Claude Code +### Cursor -You can add the Sourcegraph MCP server to [Claude Code](https://claude.ai/code) in two ways: +Add the following to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` for a project: -#### Option 1: Project-scoped server (via .mcp.json file) +```json +{ + "mcpServers": { + "sourcegraph": { + "url": "https://sourcegraph.example.com/.api/mcp" + } + } +} +``` -1. Create a `.mcp.json` file in your project root if it doesn't exist. -2. Add the following configuration: +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. + +To authenticate with a Sourcegraph access token instead, set `SOURCEGRAPH_ACCESS_TOKEN` in Cursor's environment and add an authorization header: + +```json +{ + "mcpServers": { + "sourcegraph": { + "url": "https://sourcegraph.example.com/.api/mcp", + "headers": { + "Authorization": "token ${env:SOURCEGRAPH_ACCESS_TOKEN}" + } + } + } +} +``` - ```json - { - "mcpServers": { - "sourcegraph": { - "type": "http", - "url": "https://your-sourcegraph-instance.com/.api/mcp", - "headers": { - "Authorization": "token YOUR_ACCESS_TOKEN" - } - } - } - } - ``` +### Copilot - - Replace `your-sourcegraph-instance.com` with your Sourcegraph instance - URL and `YOUR_ACCESS_TOKEN` with your access token. - +Add the Sourcegraph MCP server to [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers): -3. Save the configuration file. -4. Restart Claude Code to apply the new configuration. +```bash +copilot mcp add --transport http sourcegraph https://sourcegraph.example.com/.api/mcp +``` -#### Option 2: Locally-scoped server (via CLI command) +Then run `/mcp auth sourcegraph` and follow the authentication flow. -You can also add the Sourcegraph MCP server as a locally-scoped server, which is only available to you in the current project: +### OpenCode -1. Run the following command in your terminal: +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: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + "sourcegraph": { + "type": "remote", + "url": "https://sourcegraph.example.com/.api/mcp" + } + } +} +``` - ```bash - claude mcp add --transport http sourcegraph https://your-sourcegraph-instance.com/.api/mcp \ - --header "Authorization: token YOUR_ACCESS_TOKEN" - ``` +Then authenticate with `opencode mcp auth sourcegraph`. See [OpenCode's MCP documentation](https://opencode.ai/docs/mcp-servers/) for more information. + +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}" + } + } + } +} +``` - - Replace `your-sourcegraph-instance.com` with your Sourcegraph instance - URL and `YOUR_ACCESS_TOKEN` with your access token. - +### Amp + +Add the Sourcegraph MCP server to [Amp](https://ampcode.com/manual#mcp): + +```bash +amp mcp add sourcegraph https://sourcegraph.example.com/.api/mcp +``` + +Amp starts the OAuth flow in your browser when it connects to the server. + +To authenticate with a Sourcegraph access token instead, add an authorization header: -Locally-scoped servers take precedence over project-scoped servers with the same name and are stored in your project-specific user settings. +```bash +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`: + +```json +{ + "amp.mcpServers": { + "sourcegraph": { + "url": "https://sourcegraph.example.com/.api/mcp", + "headers": { + "Authorization": "token ${SOURCEGRAPH_ACCESS_TOKEN}" + } + } + } +} +``` + +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). ### Google Gemini Code Assist @@ -174,33 +247,6 @@ code --add-mcp "{ \"name\": \"sourcegraph\", \"type\": \"remote\", \"url\": \"ht 3. Save the configuration file. 4. Restart VS Code to apply the new configuration. -#### Cursor - -1. Open or create the MCP configuration file at `~/.cursor/mcp.json` (or the equivalent path on your system). -2. Add the following: - - ```json - { - "mcpServers": { - "sourcegraph": { - "url": "https://your-sourcegraph-instance.com/.api/mcp", - "type": "http", - "headers": { - "Authorization": "token YOUR_ACCESS_TOKEN" - } - } - } - } - ``` - - - Replace `your-sourcegraph-instance.com` with your Sourcegraph instance - URL and `YOUR_ACCESS_TOKEN` with your access token. - - -3. Save the configuration file. -4. Restart Cursor to apply the new configuration. - #### Antigravity 1. Create ⁠`.vscode/mcp.json` (Antigravity uses `.vscode` for configs) in your project. @@ -251,63 +297,3 @@ code --add-mcp "{ \"name\": \"sourcegraph\", \"type\": \"remote\", \"url\": \"ht 3. Save the configuration file. - -### OpenCode - -You can add the Sourcegraph MCP server to OpenCode by configuring it in your MCP settings file: - -1. Open or create the MCP configuration file at `~/.config/opencode/opencode.jsonc` (or the equivalent path on your system). -2. Add the following configuration: - - ```json - { - "mcp": { - "sourcegraph": { - "type": "remote", - "url": "https://your-sourcegraph-instance.com/.api/mcp", - "oauth": false, - "headers": { - "Authorization": "token {env:YOUR_ACCESS_TOKEN}" - } - } - }, - "$schema": "https://opencode.ai/config.json" - } - ``` - - - Replace `your-sourcegraph-instance.com` with your Sourcegraph instance - URL and `YOUR_ACCESS_TOKEN` with your access token. - - -3. Save the configuration file. -4. Restart OpenCode to apply the changes. - -### Codex - -You can add the Sourcegraph MCP server to [OpenAI Codex](https://github.com/openai/codex) by editing its `config.toml` file (default `~/.codex/config.toml`, or a project-scoped `.codex/config.toml`): - -1. Open or create the configuration file at `~/.codex/config.toml` (or `.codex/config.toml` in your project). -2. Add the following configuration: - - ```toml - [mcp_servers.sourcegraph] - url = "https://your-sourcegraph-instance.com/.api/mcp" - scopes = ["mcp"] - ``` - - - Replace `your-sourcegraph-instance.com` with your Sourcegraph instance - URL. - - - - `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. - - -3. Save the configuration file. -4. Restart Codex and complete the Codex OAuth login flow to sign in to your Sourcegraph instance. diff --git a/docs/api/mcp/index.mdx b/docs/api/mcp/index.mdx index 0d6dd59b7..0136f10f8 100644 --- a/docs/api/mcp/index.mdx +++ b/docs/api/mcp/index.mdx @@ -17,21 +17,7 @@ The Sourcegraph Model Context Protocol (MCP) Server provides AI agents and appli ## Getting Started -MCP clients that support OAuth can connect directly—just point them at your Sourcegraph instance and authenticate through your browser: - -**[Amp](https://ampcode.com/)** - -```bash -amp mcp add sg https://sourcegraph.example.com/.api/mcp -``` - -**[Claude Code](https://www.claude.com/product/claude-code)** - -```bash -claude mcp add --transport http sg https://sourcegraph.example.com/.api/mcp -``` - -This works similarly for other MCP-compatible agents. See [Client Integrations](/api/mcp/client-integrations) for detailed setup instructions for each client. +MCP clients that support OAuth can connect directly to your Sourcegraph instance and authenticate through your browser. See [Client Integrations](/api/mcp/client-integrations) for setup instructions for Claude Code, Codex, Cursor, Copilot, OpenCode, Amp, and other supported clients. ## Server Endpoints