Sourcegraph MCP Server: Setup, Tools & Real Limits
Sourcegraph MCP gives coding agents first-party access to enterprise code search, but its value depends on disciplined scoping and realistic expectations.
Sourcegraph MCP is Sourcegraph’s first-party bridge from AI coding clients to indexed code, history, navigation, and Deep Search. It is best for agents that must investigate several repositories without cloning them. It is not a code-writing server, a free add-on, or a substitute for controlling which repositories an agent may read.
Table of contents
- What Sourcegraph MCP actually is
- What exists today
- How to set up Sourcegraph MCP
- Tools you get
- Permissions and blast radius
- Real limits
- When not to use it
What Sourcegraph MCP actually is
Sourcegraph MCP is a remote MCP endpoint that lets a compatible agent ask Sourcegraph for code and repository context. Once connected, the agent can find a repository, search exact or natural-language terms, read selected files, inspect commits and diffs, navigate symbols, and optionally start a Deep Search investigation.
That matters most in a large organization where the answer crosses service boundaries. An agent can locate an API definition, find its callers in another repository, inspect the commit that changed it, and pull only the relevant lines into its working context. Sourcegraph documents three HTTP endpoints: /.api/mcp for the core reading suite, /.api/mcp/all for every published tool, and /.api/mcp/deepsearch for Deep Search alone (Sourcegraph MCP documentation).
MCP Directory recommends the default endpoint: fewer exposed tools mean fewer agent choices to audit. Our MCP capabilities guide explains this focused-tool approach.
What exists today
There is now an official Sourcegraph MCP server, delivered by the Sourcegraph instance itself and supported on Enterprise plans. That makes old community wrappers a legacy choice for most teams, not the default installation path.
Community packages still appear in search, but a wrapper adds a dependency, separate credential handling, and a schema that can drift. The vendor endpoint has official instructions for major coding clients (client integrations).
For production, choose the official endpoint. Consider a wrapper only when the Enterprise feature is unavailable and your team will maintain it; otherwise browse official MCP servers.
How to set up Sourcegraph MCP
Setup requires a Sourcegraph Enterprise instance, an enabled MCP service, repository access, and an MCP client that can reach the instance over HTTPS. Prefer browser-based OAuth; use a scoped access token only when the client cannot complete OAuth or when non-interactive automation genuinely requires it.
- Ask the Sourcegraph administrator to confirm
mcp.enabledis on and your role hasMCP#ACCESS. The setting defaults to enabled, but administrators can disable the service or individual tools. - Choose
https://YOUR-SOURCEGRAPH-HOST/.api/mcpunless you specifically need/allor/deepsearch. Do not copysourcegraph.example.comliterally. - Add that URL to your client. With OAuth-capable clients, connect and complete the browser authorization flow. Sourcegraph supports Dynamic Client Registration and pre-registered OAuth clients.
- If using OAuth, request only the
mcpscope. Aninvalid_scopeerror usually means the client requested something else. - If OAuth is unavailable, create a time-limited access token with the
mcpscope and supplyAuthorization: token YOUR_ACCESS_TOKEN. Keep the value in the environment or a secret store, never in a committed project file. - Restart or reconnect the client, list the exposed tools, and test with a narrowly scoped repository query.
For Claude Code, Sourcegraph publishes this project configuration shape; it is a real remote server, so there is no package command to invent:
{
"mcpServers": {
"sourcegraph": {
"type": "http",
"url": "https://sourcegraph.example.com/.api/mcp",
"headers": {
"Authorization": "token ${SOURCEGRAPH_ACCESS_TOKEN}"
}
}
}
}
The exact interpolation syntax differs by client. Use Sourcegraph’s client-specific example or adapt it with the MCP config generator, rather than assuming one JSON block is portable. Sourcegraph’s authentication guide confirms that DCR-created applications are restricted to the mcp scope and that access tokens can also be limited to that scope (MCP authentication).
Tools you get
The default endpoint exposes focused read and analysis tools; /all adds the complete published set. The table below uses the exact tool names in Sourcegraph’s current documentation, not names from a community wrapper.
| Tool | What it does |
|---|---|
list_repos | Finds repositories by name |
list_files | Lists a repository path |
read_file | Reads a file or line range |
keyword_search | Runs exact keyword search |
nls_search | Runs natural-language search |
code_finder | Locates task-relevant code |
commit_search | Searches commits and changes |
diff_search | Searches added or removed code |
evaluator | Runs sandboxed Lua on results |
deepsearch_read | Reads a Deep Search conversation |
go_to_definition | Resolves a symbol definition |
find_references | Finds symbol references |
compare_revisions | Compares two revisions |
get_contributor_repos | Finds a contributor’s repositories |
deepsearch | Starts a Deep Search conversation |
Start with list_repos, then search, then read_file. The default endpoint reads but cannot create Deep Search conversations (tool matrix).
Permissions and blast radius
Treat Sourcegraph MCP as read-only access to sensitive intellectual property. Its documented tools do not commit code, open pull requests, modify repositories, or administer Sourcegraph, but they can disclose any indexed code the authenticated identity is allowed to read.
The server checks both MCP#ACCESS and existing repository permissions. That is useful isolation only if permission syncing is correctly licensed and configured; Sourcegraph warns that without the required acls feature, repositories are treated as public to anyone who can access the instance (repository permissions).
For an individual developer, per-user OAuth is preferable because results follow that person’s repository access and revocation path. For CI or a shared agent, use a dedicated, non-admin integration account with only the repositories needed, plus a short-lived mcp-scoped token. Never use a site-admin token: site admins bypass repository permission checks by default.
A careless Sourcegraph MCP call cannot write a bad patch by itself. The real system-specific cost is leaking private code into model context, logs, or another connected tool; an agent with a separate filesystem or GitHub write tool could then act on misunderstood search results. Disable unnecessary tools with mcp.tools.disabled, keep approvals on downstream writes, and audit at the identity boundary.
Real limits
The limiting factor is usually retrieval shape, not whether Sourcegraph can find code. Search results must still fit the MCP response and the model’s context window, so broad searches can be truncated, time out, or crowd out the code the agent actually needs.
Concrete limits include these:
read_filereturns only the first 200 lines for files over 128 KB unless line ranges are requested.list_filesstops at 1,000 entries.commit_searchtops out at 100 results;diff_searchat 50;compare_revisionsat 100 file diffs per page.- Normal Sourcegraph search defaults to a 10-second timeout, while administrators normally cap user-selected timeouts at one minute.
- Files larger than 1 MB are excluded from code search by default, and binary and non-UTF-8 files are not indexed.
- Code Finder is beta and metered against the instance entitlement; exhausted quota returns an error.
Sourcegraph publishes no universal numeric MCP request-per-minute limit, so do not promise one. Capacity depends on the deployment, and upstream code-host limits can delay repository discovery, syncing, and freshness (rate-limit guidance). Unscoped results across many repositories may also lag the latest default branches, whereas repository-scoped searches trigger fresher fetching (code search capabilities).
Most importantly, this API cannot edit files, create branches, submit reviews, run builds, or manage the search index. For exhaustive, long-running inventories, Sourcegraph Search Jobs or a Stream API script is a better fit than pouring thousands of matches through an LLM; Search Jobs are explicitly designed to avoid ordinary query timeouts and incomplete results (Search Jobs).
When not to use it
Do not use Sourcegraph MCP when a human-facing Sourcegraph workflow or a deterministic script solves the task more cheaply and predictably. MCP earns its place when an agent must choose and combine searches interactively across repositories.
Use Sourcegraph’s own Deep Search when the goal is one substantial codebase investigation and you do not need the answer inside another agent. Use the Stream API or src CLI for repeatable exports, compliance scans, counts, or count:all searches; those interfaces preserve structured results without spending model context on every match (streaming search API). Use local ripgrep when the repository is already cloned and the question is narrow.
I would also skip Sourcegraph MCP for small teams buying Sourcegraph only for this connector. The current Enterprise plan includes MCP and starts at $16,000, with AI credits and scaling tied to the commercial plan (Sourcegraph pricing). That trade-off makes sense when Sourcegraph is already the organization’s cross-repository search layer. Otherwise, compare the best MCP servers and use the code host’s official connector or a plain API script until the indexing and governance benefits justify the platform cost.