MCP server

The Sourcegraph MCP server exposes your Sourcegraph instance’s code search, navigation, and analysis capabilities to AI agents and applications through the Model Context Protocol (MCP). Any MCP-compatible tool can connect to it and use Sourcegraph as a context source.

The Sourcegraph MCP server is available on Enterprise plans.

Quick start

MCP clients that support OAuth can connect with a single command — no manual token setup required:

Amp
Claude Code

amp mcp add sg https://sourcegraph.example.com/.api/mcp

claude mcp add --transport http sg https://sourcegraph.example.com/.api/mcp

Both commands prompt you to authenticate through your browser the first time. Replace sourcegraph.example.com with your Sourcegraph instance URL.

Server endpoints

Endpoint	Description
`/.api/mcp`	Full suite of Sourcegraph tools
`/.api/mcp/deepsearch`	Deep Search agent endpoint

Authentication

OAuth 2.0 (recommended)

Sourcegraph implements Dynamic Client Registration (RFC 7591), so compatible clients register automatically without requiring a pre-configured client ID. DCR-registered applications are granted the mcp scope, which restricts access to MCP endpoints only. If your client doesn’t support Dynamic Client Registration, you can manually create an OAuth application in your Sourcegraph instance and use mcp-remote as a bridge:

{
  "sourcegraph": {
    "type": "stdio",
    "command": "npx",
    "args": [
      "mcp-remote",
      "https://sourcegraph.example.com/.api/mcp",
      "3334",
      "--static-oauth-client-info",
      "{\"client_id\":\"YOUR_CLIENT_ID\"}",
      "--static-oauth-client-metadata",
      "{\"scope\":\"mcp\"}"
    ]
  }
}

Set the OAuth client’s redirect URI to http://localhost:3334/oauth/callback when using this approach.

Access token

Include a Sourcegraph access token in the Authorization header. You can use the mcp scope to restrict the token to MCP endpoints only:

Authorization: token YOUR_ACCESS_TOKEN

Client setup

Amp

CLI
VS Code settings.json

amp mcp add sourcegraph \
  --header "Authorization=token YOUR_ACCESS_TOKEN" \
  https://sourcegraph.example.com/.api/mcp

{
  "amp.mcpServers": {
    "sourcegraph": {
      "url": "https://sourcegraph.example.com/.api/mcp",
      "headers": {
        "Authorization": "token YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Claude Code

CLI
.mcp.json

claude mcp add --transport http sourcegraph \
  https://sourcegraph.example.com/.api/mcp \
  --header "Authorization: token YOUR_ACCESS_TOKEN"

Create .mcp.json in your project root:

{
  "mcpServers": {
    "sourcegraph": {
      "type": "http",
      "url": "https://sourcegraph.example.com/.api/mcp",
      "headers": {
        "Authorization": "token YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Cursor

Create or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "sourcegraph": {
      "url": "https://sourcegraph.example.com/.api/mcp",
      "type": "http",
      "headers": {
        "Authorization": "token YOUR_ACCESS_TOKEN"
      }
    }
  }
}

VS Code

CLI
.vscode/mcp.json

code --add-mcp '{"name":"sourcegraph","type":"remote","url":"https://sourcegraph.example.com/.api/mcp"}'

{
  "servers": {
    "sourcegraph": {
      "type": "http",
      "url": "https://sourcegraph.example.com/.api/mcp"
    }
  },
  "inputs": []
}

Windsurf

Create ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "sourcegraph": {
      "serverUrl": "https://sourcegraph.example.com/.api/mcp",
      "headers": {
        "Authorization": "token YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json"
      }
    }
  }
}

OpenCode

Edit ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "sourcegraph": {
      "type": "remote",
      "url": "https://sourcegraph.example.com/.api/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "token {env:YOUR_ACCESS_TOKEN}"
      }
    }
  },
  "$schema": "https://opencode.ai/config.json"
}

Google Gemini Code Assist

Edit ~/.gemini/settings.json:

{
  "mcpServers": {
    "sourcegraph": {
      "httpUrl": "https://sourcegraph.example.com/.api/mcp",
      "headers": {
        "Authorization": "token YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Available tools

All tools implement result limits to prevent context window overflow. For large result sets, use pagination cursors (after/before) or narrow your search with more specific filters.

File and repository operations

Tool	Description
`read_file`	Read file contents with line numbers. Supports line ranges and specific revisions. Max file size: 128 KB.
`list_files`	List files and directories in a repository path.
`list_repos`	Search and list repositories by name pattern with pagination.

Code search

Tool	Description
`keyword_search`	Exact keyword search with boolean operators (`AND`/`OR`), regex, and filters (`repo:`, `file:`, `rev:`).
`nls_search`	Semantic search with natural language matching, stemming, and broader results than keyword search.

Tool	Description
`go_to_definition`	Find a symbol’s definition from a usage location. Cross-repository, compiler-accurate.
`find_references`	Find all references to a symbol from its definition location.

Version control and history

Tool	Description
`commit_search`	Search commits by message, author, content, file paths, and date range.
`diff_search`	Search actual code changes (diffs) for specific patterns. Filter by added/removed lines, author, and date.
`compare_revisions`	Show the diff between two revisions of a repository.
`get_contributor_repos`	Find repositories a contributor has committed to.

Deep Search

Tool	Description
`deepsearch`	Ask a detailed question about your codebase. Deep Search performs multi-step research and returns a comprehensive answer with evidence.
`deepsearch_read`	Read a previous Deep Search conversation by URL or read token.

Admins can disable the deepsearch tool on the default MCP endpoint by contacting your account team or adjusting site configuration. This does not affect the dedicated /.api/mcp/deepsearch endpoint.

Best practices

Start with repository discovery

Use list_repos first to identify the repositories relevant to your task. Scoping subsequent searches to specific repositories improves performance and result quality.

Search broadly, then narrow

Start with nls_search for natural language queries, then use keyword_search with specific filters once you know what you’re looking for.

Verify before reading

Use list_files to confirm a file exists before calling read_file. For large files, use startLine/endLine parameters to read only the relevant section.

Chain tools together

Combine tools for richer analysis: list_repos → keyword_search → go_to_definition → find_references.

Paginate large result sets

Use after/before cursors for tools that support pagination (list_repos, compare_revisions, get_contributor_repos).

Administration

Integrations & API

Quick start

Server endpoints

Authentication

OAuth 2.0 (recommended)

Access token

Client setup

Amp

Claude Code

Cursor

VS Code

Windsurf

OpenCode

Google Gemini Code Assist

Available tools

File and repository operations

Code search

Code navigation

Version control and history

Deep Search

Best practices

Build docs developers (and LLMs) love

Administration

Integrations & API

​Quick start

​Server endpoints

​Authentication

​OAuth 2.0 (recommended)

​Access token

​Client setup

​Amp

​Claude Code

​Cursor

​VS Code

​Windsurf

​OpenCode

​Google Gemini Code Assist

​Available tools

​File and repository operations

​Code search

​Code navigation

​Version control and history

​Deep Search

​Best practices

Build docs developers (and LLMs) love

Quick start

Server endpoints

Authentication

OAuth 2.0 (recommended)

Access token

Client setup

Amp

Claude Code

Cursor

VS Code

Windsurf

OpenCode

Google Gemini Code Assist

Available tools

File and repository operations

Code search

Code navigation

Version control and history

Deep Search

Best practices