Sourcegraph MCP Server
Connect AI agents and applications to your Sourcegraph instance's code search and analysis capabilities.
Supported on Enterprise plans.
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.
Server Endpoint
The MCP server is available at:
SHELLhttps://your-sourcegraph-instance.com/.api/mcp/v1
Authentication
The Sourcegraph MCP server supports two authentication methods:
OAuth 2.0
For programmatic access without storing credentials, use OAuth 2.0 with device flow or authorization code flow with PKCE:
Prerequisites
Before using OAuth, you must create an OAuth application in your Sourcegraph instance. Follow the instructions here. (Note: you will need the user:all
scope)
Authorization Header
Include your token in the Authorization header:
SHELLAuthorization: token YOUR_ACCESS_TOKEN
Client Integration
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.
You can add the Sourcegraph MCP server to Amp in two ways:
Option 1: VSCode settings.json
-
Open VSCode's
settings.json
file. -
Add the following configuration:
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 andYOUR_ACCESS_TOKEN
with your access token. -
Save the configuration file.
-
Restart VS Code to apply the new configuration.
Option 2: Amp CLI
Run the following command in your terminal:
BASHamp 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.
Claude Code
You can add the Sourcegraph MCP server to Claude Code in two ways:
Option 1: Project-scoped server (via .mcp.json file)
-
Create a
.mcp.json
file in your project root if it doesn't exist. -
Add the following configuration:
JSON{ "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 andYOUR_ACCESS_TOKEN
with your access token. -
Save the configuration file.
-
Restart Claude Code to apply the new configuration.
Option 2: Locally-scoped server (via CLI command)
You can also add the Sourcegraph MCP server as a locally-scoped server, which is only available to you in the current project:
-
Run the following command in your terminal:
BASHclaude mcp add sourcegraph -s local --url https://your-sourcegraph-instance.com/.api/mcp/v1 --header "Authorization: token YOUR_ACCESS_TOKEN"
Replace
your-sourcegraph-instance.com
with your Sourcegraph instance URL andYOUR_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.
Available Tools
The MCP server provides these tools for code exploration and analysis:
File & Repository Operations
sg_read_file
Read file contents with line numbers and support for specific ranges and revisions.
Parameters:
repo
- Repository name (required)path
- File path within repository (required)startLine
- Starting line number (optional)endLine
- Ending line number (optional)revision
- Branch, tag, or commit hash (optional)
Use cases: Reading specific files, examining code sections, reviewing different versions
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)
sg_list_repos
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)
Code Search
sg_keyword_search
Perform exact keyword searches with boolean operators and filters.
Parameters:
query
- Search query with optional filters (required)
Supported filters:
repo:
- limit to specific repositoriesfile:
- search specific file patternsrev:
- search specific revisions
Features: Boolean AND/OR operators, regex patterns
sg_nls_search
Semantic search with flexible linguistic matching.
Parameters:
query
- Natural language search query (required)
Supported filters:
repo:
- limit to specific repositoriesfile:
- search specific file patternsrev:
- search specific revisions
Features: Flexible linguistic matching, stemming, broader results than keyword search
Code Navigation
sg_go_to_definition
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)revision
- Branch, tag, or commit hash (optional)
Features: Cross-repository support, compiler-level accuracy
sg_find_references
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)revision
- Branch, tag, or commit hash (optional)
Version Control & History
sg_commit_search
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)contentTerms
- Search in actual code changes (optional)files
- Filter by file paths (optional)after
/before
- Date range filters (optional)
sg_diff_search
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)removed
- Search only removed code (optional)author
- Filter by author (optional)after
/before
- Date range filters (optional)
sg_compare_revisions
Compare changes between two specific revisions.
Parameters:
repo
- Repository name (required)base
- Base revision (older version) (required)head
- Head revision (newer version) (required)first
- Maximum file diffs to return (optional, default 50)after
- Pagination cursor (optional)
sg_get_contributor_repos
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" } } }
Reading a Specific File
JSON{ "method": "tools/call", "params": { "name": "sg_read_file", "arguments": { "repo": "github.com/myorg/myrepo", "path": "src/auth/login.go", "startLine": 1, "endLine": 50 } } }
Finding Recent Changes
JSON{ "method": "tools/call", "params": { "name": "sg_commit_search", "arguments": { "repos": ["github.com/myorg/myrepo"], "messageTerms": ["bug fix"], "after": "1 week ago" } } }
Best Practices
- Repository Scoping: Use
sg_list_repos
first to find relevant repositories for better performance - Progressive Search: Start with broad searches (
sg_nls_search
) then narrow with specific tools - File Verification: Use
sg_list_files
beforesg_read_file
to verify file existence - Pagination: Use
after
/before
cursors for large result sets - Tool Combinations: Chain tools together (e.g.,
sg_list_repos
→sg_commit_search
)