Title: Sourcegraph MCP Server - Sourcegraph docs
URL Source: https://sourcegraph.com/docs/api/mcp
Markdown Content:
Connect AI agents and applications to your Sourcegraph instance's code search and analysis capabilities.
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.
The MCP server provides different tool suites for various use cases:
| Endpoint | Description |
|---|
/.api/mcp | Core Sourcegraph search, repository, history, and Deep Search reading tools |
/.api/mcp/all | Full suite of Sourcegraph tools |
/.api/mcp/deepsearch | Deep Search agent tools only |
Example URL:
SHELL
https://sourcegraph.example.com/.api/mcp
The MCP server supports OAuth 2.0 through Dynamic Client Registration or pre-registered OAuth clients, as well as Sourcegraph access tokens. Organizations that require administrators to approve OAuth clients can configure static OAuth clients and disable Dynamic Client Registration.
See MCP Authentication to choose and configure an authentication method.
Admins can control MCP at three levels:
- Advanced configuration:
mcp.enabled enables or disables the MCP HTTP endpoints.
- Tool-level configuration:
mcp.tools.disabled disables individual MCP tools by name.
- OAuth Dynamic Client Registration:
auth.idpDynamicClientRegistrationEnabled controls whether OAuth clients can self-register. See MCP Authentication to disable DCR and configure pre-registered clients.
- RBAC: users must have the
MCP#ACCESS permission to use MCP.
Use the mcp.enabled advanced configuration to turn the MCP server on or off for the entire instance:
JSON
{
"mcp.enabled": true
}
mcp.enabled defaults to true. When set to false, requests to /.api/mcp and its subpaths return 404 no route.
Use the mcp.tools.disabled advanced configuration setting to remove specific tools from all MCP endpoints while keeping the rest of the server available. The setting takes an array of strings, where each string is the name of a tool to disable - e.g. code_finder or deepsearch:
JSON
{
"mcp.tools.disabled": ["code_finder", "deepsearch"]
}
Tool names match the headings in Available Tools below. Disabled tools are omitted from the tool list that MCP clients see, and calls to them are rejected.
When MCP is enabled, Sourcegraph also checks the MCP#ACCESS permission before serving MCP requests. Users without that permission receive 403 forbidden.
By default, MCP#ACCESS is granted to the built-in User system role, so all signed-in users can access MCP unless an admin changes the default role permissions.
To restrict MCP to a subset of users:
- Open Administration > Users & auth > Roles.
- Edit the built-in User role and remove the
MCP > ACCESS permission if you want MCP denied by default.
- Create a custom role that includes
MCP > ACCESS.
- Assign that role to the users who should be allowed to use MCP.
See Access control for more about managing roles and permissions.
The MCP server provides these tools for code exploration and analysis:
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
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)
Search and list repositories by name substring.
Parameters:
query - Substring to match against repository names (required)limit - Maximum repositories to return (optional, default 50, maximum 10000)
List a repository's Git branches and tags.
Parameters:
repo - Repository name (required)tagsOnly - Return only tags (optional, default false)headsOnly - Return only branches (optional, default false)containsCommit - Return only refs whose history contains this commit (optional)limit - Maximum refs to return (optional, default 100, minimum 1, maximum 500)
Omit tagsOnly and headsOnly to return both branches and tags. The filters can also be combined.
Examples:
JSON
{"repo": "github.com/sourcegraph/sourcegraph", "limit": 500}
JSON
{"repo": "github.com/sourcegraph/sourcegraph", "tagsOnly": true}
JSON
{
"repo": "github.com/sourcegraph/sourcegraph",
"tagsOnly": true,
"containsCommit": "abc123"
}
Use cases: Listing repository branches and tags, finding release tags, identifying which releases contain a commit, and discovering a valid release tag before using tools that accept a revision such as read_file or compare_revisions
Perform exact keyword code searches.
Parameters:
query - Search query with optional filters (required)
Supported filters:
repo: - limit to specific repositoriesfile: - search specific file patternsrev: - search specific revisionscount: - set the number of returned matches
Features: Boolean AND/OR operators, exact keyword matching
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
Run sandboxed Lua scripts for aggregation, cross-referencing, and computation over search results.
Parameters:
script - Lua script to execute against Sourcegraph search results (required)
Use cases: Counting or aggregating many search matches, cross-referencing multiple searches, transforming or combining search output with custom logic
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
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)limit - Maximum references to return (optional, default 10)
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)revisions - Branches, tags, or ref globs to search (optional)count - Number of results to return (optional, default 50, maximum 100)
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)authors - Filter by authors (optional)after/before - Date range filters (optional)revisions - Branches, tags, or ref globs to search (optional)count - Maximum results to return (optional, default 20, maximum 50)
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, maximum 100)after - Pagination cursor (optional)
Find repositories where a contributor has made commits.
Parameters:
authors - Author names or email addresses (required, maximum 5)limit - Maximum repositories to return (optional, default 20, maximum 100)minCommits - Minimum commits required (optional, default 1)
Code Finder is an agentic tool that sits between plain search and Deep Search: it runs its own internal search loop to locate the code relevant to a task, then returns the matching file paths and line ranges with a brief explanation. Unlike deepsearch, it runs synchronously and is designed for quickly finding relevant code in a repository you already know, rather than open-ended research across many repositories.
Code Finder usage is metered against your instance's entitlement. When the quota is exhausted, the tool returns an error.
Find relevant code using a fast search agent.
Parameters:
task - The task or query to research and answer (required)revision - Branch, tag, or commit to search (optional; defaults to the repository's default branch). When set, task must identify a repository.
Use cases: Locating the files and line ranges relevant to a task before making changes, finding where a feature is implemented, gathering focused context for an AI agent
Best practices:
- Name the target repository. Code Finder searches a repository you already know and declines broad cross-repository discovery—identify the repository first (for example with
list_repos), then call the tool.
- Phrase the task as a precise engineering request: "In github.com/example/shop, find where we build HTTP error responses" rather than "shop error handling".
- Include what you already know: relevant paths, symbols, APIs, configuration names, or error strings and mention findings from earlier searches so the tool skips re-surfacing them and spends its search budget on the unknown parts.
- State explicit success criteria so the tool knows when to stop, such as "Return file paths and line numbers for JWT verification calls."
Output: A short summary followed by links to the relevant files and line ranges.
Create a new Deep Search conversation to answer complex questions about your codebase.
Parameters:
question - The question to research using Deep Search (required). Should be detailed and specific about what you want to understand.
Use cases: Comprehensive analysis of complex technical questions, multi-step research across one or many remote codebases, detailed explanations with supporting evidence, questions that require combining information from multiple sources
Read a Deep Search conversation and return the markdown content of the questions and answers.
Parameters:
identifier - The Deep Search conversation identifier (required). Can be:
- A full Sourcegraph Deep Search URL (e.g.,
https://sourcegraph.com/deepsearch/abc123 or https://sourcegraph.com/deepsearch/shared/abc123)
- A read token (e.g.,
abc123-def456-...)
Use cases: Reading or re-opening Deep Search results, summarizing existing answers, using past Deep Search as context for new questions
Use this matrix to choose the smallest endpoint that has the tools your MCP client needs.
| Tool | /.api/mcp | /.api/mcp/all | /.api/mcp/deepsearch |
|---|
code_finder | ✓ | ✓ | |
commit_search | ✓ | ✓ | |
compare_revisions | | ✓ | |
deepsearch | | ✓ | ✓ |
deepsearch_read | ✓ | ✓ | ✓ |
diff_search | ✓ | ✓ | |
evaluator | ✓ | ✓ | |
find_references | | ✓ | |
get_contributor_repos | | ✓ | |
go_to_definition | | ✓ | |
keyword_search | ✓ | ✓ | |
list_files | ✓ | ✓ | |
list_refs | | ✓ | |
list_repos | ✓ | ✓ | |
nls_search | | ✓ | |
read_file | ✓ | ✓ | |
On /.api/mcp, nls_search is available as a fallback when code_finder is unavailable or disabled.
If your MCP client's OAuth login fails with an invalid_scope error when connecting to /.api/mcp, the client requested a scope that the Sourcegraph identity provider does not allow for the MCP resource. MCP endpoints require the mcp scope.
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 section on the client integrations page for the full configuration.
- Repository Scoping: Use
list_repos first to find relevant repositories for better performance
- Progressive Search: Use
code_finder to locate code relevant to a task if available; otherwise, start with a broad nls_search and narrow with more specific tools like keyword_search
- Revision Discovery: Use
list_refs to find a valid branch or tag before calling tools that accept revisions
- File Verification: Use
list_files before read_file to verify file existence
- Pagination: Use
after/before cursors for large result sets
- Tool Combinations: Chain tools together (e.g.,
list_repos → list_refs → read_file)