diff --git a/docs/api/mcp/index.mdx b/docs/api/mcp/index.mdx index 9e9d3837f..79cb3a4ff 100644 --- a/docs/api/mcp/index.mdx +++ b/docs/api/mcp/index.mdx @@ -1,12 +1,17 @@ # Sourcegraph MCP Server -

Connect AI agents and applications to your Sourcegraph instance's code search and analysis capabilities.

+

+ Connect AI agents and applications to your Sourcegraph instance's code + search and analysis capabilities. +

- - Supported on [Enterprise](/pricing/enterprise) plans. - +Supported on [Enterprise](/pricing/enterprise) plans. Available in version 6.8 and above. -This feature is [experimental](admin/beta_and_experimental_features#experimental-features) and might change or be removed in the future. + + This feature is + [experimental](admin/beta_and_experimental_features#experimental-features) + and might change or be removed in the future. + The Sourcegraph Model Context Protocol (MCP) Server provides AI agents and applications with programmatic access to your Sourcegraph instance's code search, navigation, and analysis capabilities through a standardized interface. @@ -28,7 +33,7 @@ For programmatic access without storing credentials, use OAuth 2.0 with device f #### Prerequisites -Before using OAuth, you must create an OAuth application in your Sourcegraph instance. Follow the instructions [here](/admin/oauth_apps#creating-an-oauth-app). (Note: you will need the `user:all` scope) +Before using OAuth, you must create an OAuth application in your Sourcegraph instance. Follow the instructions [here](/admin/oauth_apps#creating-an-oauth-app). (Note: you will need the `user:all` scope) ### Authorization Header @@ -42,40 +47,42 @@ Authorization: token YOUR_ACCESS_TOKEN The Sourcegraph MCP server can be integrated with various AI tools and IDEs that support the Model Context Protocol. -### Amp + + - To create an access token, visit [Creating an access token](/cli/how-tos/creating_an_access_token). + To create an access token, visit [Creating an access + token](/cli/how-tos/creating_an_access_token). You can add the Sourcegraph MCP server to [Amp](https://ampcode.com) in two ways: -#### Option 1: VSCode settings.json - 1. Open VSCode's `settings.json` file. 2. Add the following configuration: - ```json - { - "amp.mcpServers": { - "sourcegraph": { - "url": "https://your-sourcegraph-instance.com/.api/mcp/v1", - "headers": { - "Authorization": "token YOUR_ACCESS_TOKEN" + ```json + { + "amp.mcpServers": { + "sourcegraph": { + "url": "https://your-sourcegraph-instance.com/.api/mcp/v1", + "headers": { + "Authorization": "token YOUR_ACCESS_TOKEN" + } } } } - } - ``` + ``` - - Replace `your-sourcegraph-instance.com` with your Sourcegraph instance URL and `YOUR_ACCESS_TOKEN` with 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 VS Code to apply the new configuration. -#### Option 2: Amp CLI + + + Run the following command in your terminal: @@ -83,11 +90,12 @@ Run the following command in your terminal: amp mcp add sourcegraph --header "Authorization=token YOUR_ACCESS_TOKEN" https://sourcegraph.sourcegraph.com/.api/mcp/v1 ``` - - Replace `sourcegraph.sourcegraph.com` with your Sourcegraph instance URL and set `YOUR_ACCESS_TOKEN` environment variable to your access token. - + + Replace `sourcegraph.sourcegraph.com` with your Sourcegraph instance URL and set `YOUR_ACCESS_TOKEN` environment variable to your access token. + + -### Claude Code + You can add the Sourcegraph MCP server to [Claude Code](https://claude.ai/code) in two ways: @@ -96,23 +104,24 @@ You can add the Sourcegraph MCP server to [Claude Code](https://claude.ai/code) 1. Create a `.mcp.json` file in your project root if it doesn't exist. 2. Add the following configuration: - ```json - { - "mcpServers": { - "sourcegraph": { - "type": "http", - "url": "https://your-sourcegraph-instance.com/.api/mcp/v1", - "headers": { - "Authorization": "token YOUR_ACCESS_TOKEN" - } - } + ```json + { + "mcpServers": { + "sourcegraph": { + "type": "http", + "url": "https://your-sourcegraph-instance.com/.api/mcp/v1", + "headers": { + "Authorization": "token YOUR_ACCESS_TOKEN" + } + } + } } - } - ``` + ``` - - Replace `your-sourcegraph-instance.com` with your Sourcegraph instance URL and `YOUR_ACCESS_TOKEN` with 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 Claude Code to apply the new configuration. @@ -123,76 +132,90 @@ You can also add the Sourcegraph MCP server as a locally-scoped server, which is 1. Run the following command in your terminal: - ```bash - claude mcp add --transport http sourcegraph https://your-sourcegraph-instance.com/.api/mcp/v1 \ - --header "Authorization: token YOUR_ACCESS_TOKEN" - ``` + ```bash + claude mcp add --transport http sourcegraph https://your-sourcegraph-instance.com/.api/mcp/v1 \ + --header "Authorization: token YOUR_ACCESS_TOKEN" + ``` - - Replace `your-sourcegraph-instance.com` with your Sourcegraph instance URL and `YOUR_ACCESS_TOKEN` with your access token. - + + Replace `your-sourcegraph-instance.com` with your Sourcegraph instance + URL and `YOUR_ACCESS_TOKEN` with your access token. + Locally-scoped servers take precedence over project-scoped servers with the same name and are stored in your project-specific user settings. -### Google Gemini Code Assist + + + You can add the Sourcegraph MCP server to Google Gemini Code Assist by configuring the `.gemini/settings.json` file: 1. Open or create the configuration file at `~/.gemini/settings.json` (or the equivalent path on your system). 2. Add the following configuration: - ```json - { - "mcpServers": { - "sourcegraph": { - "httpUrl": "https://your-sourcegraph-instance.com/.api/mcp/v1", - "headers": { - "Authorization": "token YOUR_ACCESS_TOKEN" + ```json + { + "mcpServers": { + "sourcegraph": { + "httpUrl": "https://your-sourcegraph-instance.com/.api/mcp/v1", + "headers": { + "Authorization": "token YOUR_ACCESS_TOKEN" + } } } } - } - ``` + ``` - - Replace `your-sourcegraph-instance.com` with your Sourcegraph instance URL and `YOUR_ACCESS_TOKEN` with 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 Gemini Code Assist to apply the new configuration. -### Cursor + + + You can add the Sourcegraph MCP server to Cursor by configuring it in your MCP settings file: 1. Open or create the MCP configuration file at `~/.cursor/mcp.json` (or the equivalent path on your system). 2. Add the following configuration: - ```json - { - "mcpServers": { - "sourcegraph": { - "type": "http", - "url": "https://your-sourcegraph-instance.com/.api/mcp/v1", - "headers": { - "Authorization": "token YOUR_ACCESS_TOKEN" - } - } + ```json + { + "mcpServers": { + "sourcegraph": { + "type": "http", + "url": "https://your-sourcegraph-instance.com/.api/mcp/v1", + "headers": { + "Authorization": "token YOUR_ACCESS_TOKEN" + } + } + } } - } - ``` + ``` - - Replace `your-sourcegraph-instance.com` with your Sourcegraph instance URL and `YOUR_ACCESS_TOKEN` with your access token. Note that Cursor requires the `type: "http"` field to be explicitly specified. - + + Replace `your-sourcegraph-instance.com` with your Sourcegraph instance + URL and `YOUR_ACCESS_TOKEN` with your access token. Note that Cursor + requires the `type: "http"` field to be explicitly specified. + 3. Save the configuration file. 4. Restart Cursor to apply the new configuration. + + + ## Available Tools -All MCP tools implement result limits to ensure efficient operation and prevent context window overflow. These limits are designed to return the most relevant results while maintaining optimal performance. For large result sets, use pagination parameters (`after`/`before` cursors) where available, or refine your search with more specific filters. + All MCP tools implement result limits to ensure efficient operation and + prevent context window overflow. These limits are designed to return the + most relevant results while maintaining optimal performance. For large + result sets, use pagination parameters (`after`/`before` cursors) where + available, or refine your search with more specific filters. The MCP server provides these tools for code exploration and analysis: @@ -213,13 +236,16 @@ Read file contents with line numbers and support for specific ranges and revisio **Use cases:** Reading specific files, examining code sections, reviewing different versions -File size limit is 128KB. Use line ranges for larger files. + + File size limit is 128KB. Use line ranges for larger files. + #### `sg_list_files` List files and directories in a repository path. **Parameters:** + - `repo` - Repository name (required) - `path` - Directory path (optional, defaults to root) - `revision` - Branch, tag, or commit hash (optional) @@ -229,6 +255,7 @@ List files and directories in a repository path. Search and list repositories by name patterns with pagination support. **Parameters:** + - `query` - Search pattern for repository names (required) - `limit` - Maximum results per page (optional, default 50) - `after`/`before` - Pagination cursors (optional) @@ -240,9 +267,11 @@ Search and list repositories by name patterns with pagination support. Perform exact keyword searches with boolean operators and filters. **Parameters:** + - `query` - Search query with optional filters (required) **Supported filters:** + - `repo:` - limit to specific repositories - `file:` - search specific file patterns - `rev:` - search specific revisions @@ -254,9 +283,11 @@ Perform exact keyword searches with boolean operators and filters. Semantic search with flexible linguistic matching. **Parameters:** + - `query` - Natural language search query (required) **Supported filters:** + - `repo:` - limit to specific repositories - `file:` - search specific file patterns - `rev:` - search specific revisions @@ -270,6 +301,7 @@ Semantic search with flexible linguistic matching. Find the definition of a symbol from a usage location. **Parameters:** + - `repo` - Repository name (required) - `path` - File path containing symbol usage (required) - `symbol` - Symbol name to find definition for (required) @@ -282,6 +314,7 @@ Find the definition of a symbol from a usage location. Find all references to a symbol from its definition location. **Parameters:** + - `repo` - Repository name (required) - `path` - File path containing symbol definition (required) - `symbol` - Symbol name to find references for (required) @@ -294,6 +327,7 @@ Find all references to a symbol from its definition location. Search commits by message, author, content, files, and date ranges. **Parameters:** + - `repos` - Array of repository names (required) - `messageTerms` - Terms to search in commit messages (optional) - `authors` - Filter by commit authors (optional) @@ -306,6 +340,7 @@ Search commits by message, author, content, files, and date ranges. Search actual code changes for specific patterns across repositories. **Parameters:** + - `pattern` - Search pattern for code changes (required) - `repos` - Array of repository names (required) - `added` - Search only added code (optional) @@ -318,6 +353,7 @@ Search actual code changes for specific patterns across repositories. Compare changes between two specific revisions. **Parameters:** + - `repo` - Repository name (required) - `base` - Base revision (older version) (required) - `head` - Head revision (newer version) (required) @@ -329,25 +365,24 @@ Compare changes between two specific revisions. Find repositories where a contributor has made commits. **Parameters:** + - `author` - Author name or email (required) - `limit` - Maximum repositories to return (optional, default 20) - `minCommits` - Minimum commits required (optional, default 1) - - ## Usage Examples ### Finding Authentication Code ```json { - "method": "tools/call", - "params": { - "name": "sg_nls_search", - "arguments": { - "query": "authentication login user" - } - } + "method": "tools/call", + "params": { + "name": "sg_nls_search", + "arguments": { + "query": "authentication login user" + } + } } ``` @@ -355,16 +390,16 @@ Find repositories where a contributor has made commits. ```json { - "method": "tools/call", - "params": { - "name": "sg_read_file", - "arguments": { - "repo": "github.com/myorg/myrepo", - "path": "src/auth/login.go", - "startLine": 1, - "endLine": 50 - } - } + "method": "tools/call", + "params": { + "name": "sg_read_file", + "arguments": { + "repo": "github.com/myorg/myrepo", + "path": "src/auth/login.go", + "startLine": 1, + "endLine": 50 + } + } } ``` @@ -372,15 +407,15 @@ Find repositories where a contributor has made commits. ```json { - "method": "tools/call", - "params": { - "name": "sg_commit_search", - "arguments": { - "repos": ["github.com/myorg/myrepo"], - "messageTerms": ["bug fix"], - "after": "1 week ago" - } - } + "method": "tools/call", + "params": { + "name": "sg_commit_search", + "arguments": { + "repos": ["github.com/myorg/myrepo"], + "messageTerms": ["bug fix"], + "after": "1 week ago" + } + } } ```