Skip to content

Commit e376711

Browse files
docs(sourcegraph): add docs for the MCP server (#1351)
Adds documentation for the Sourcegraph MCP server added in v6.8 ## Pull Request approval You will need to get your PR approved by at least one member of the Sourcegraph team. For reviews of docs formatting, styles, and component usage, please tag the docs team via the #docs Slack channel.
1 parent 06fee07 commit e376711

File tree

3 files changed

+251
-0
lines changed

3 files changed

+251
-0
lines changed

docs/api/index.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@ Sourcegraph exposes the following APIs:
44

55
- [Sourcegraph GraphQL API](/api/graphql/), for accessing data stored or computed by Sourcegraph
66
- [Sourcegraph Stream API](/api/stream_api/), for consuming search results as a stream of events
7+
- [Sourcegraph MCP Server](/api/mcp/), for connecting AI agents and applications to Sourcegraph's code search capabilities

docs/api/mcp/index.mdx

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
# Sourcegraph MCP Server
2+
3+
<p className="subtitle">Connect AI agents and applications to your Sourcegraph instance's code search and analysis capabilities.</p>
4+
5+
<TierCallout>
6+
Supported on [Enterprise](/pricing/enterprise) plans.
7+
</TierCallout>
8+
<Callout type="note">This feature is [experimental](admin/beta_and_experimental_features#experimental-features) and might change or be removed in the future.</Callout>
9+
10+
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.
11+
12+
## Server Endpoint
13+
14+
The MCP server is available at:
15+
16+
```
17+
https://your-sourcegraph-instance.com/.api/mcp/v1
18+
```
19+
20+
## Authentication
21+
22+
The Sourcegraph MCP server supports two authentication methods:
23+
24+
### OAuth 2.0
25+
26+
For programmatic access without storing credentials, use OAuth 2.0 with device flow or authorization code flow with PKCE:
27+
28+
#### Prerequisites
29+
30+
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)
31+
32+
### Authorization Header
33+
34+
Include your token in the Authorization header:
35+
36+
```
37+
Authorization: token YOUR_ACCESS_TOKEN
38+
```
39+
40+
## Available Tools
41+
42+
The MCP server provides these tools for code exploration and analysis:
43+
44+
### File & Repository Operations
45+
46+
#### `sg_read_file`
47+
48+
Read file contents with line numbers and support for specific ranges and revisions.
49+
50+
**Parameters:**
51+
52+
- `repo` - Repository name (required)
53+
- `path` - File path within repository (required)
54+
- `startLine` - Starting line number (optional)
55+
- `endLine` - Ending line number (optional)
56+
- `revision` - Branch, tag, or commit hash (optional)
57+
58+
**Use cases:** Reading specific files, examining code sections, reviewing different versions
59+
60+
<Callout type="note">File size limit is 128KB. Use line ranges for larger files.</Callout>
61+
62+
#### `sg_list_files`
63+
64+
List files and directories in a repository path.
65+
66+
**Parameters:**
67+
- `repo` - Repository name (required)
68+
- `path` - Directory path (optional, defaults to root)
69+
- `revision` - Branch, tag, or commit hash (optional)
70+
71+
#### `sg_list_repos`
72+
73+
Search and list repositories by name patterns with pagination support.
74+
75+
**Parameters:**
76+
- `query` - Search pattern for repository names (required)
77+
- `limit` - Maximum results per page (optional, default 50)
78+
- `after`/`before` - Pagination cursors (optional)
79+
80+
### Code Search
81+
82+
#### `sg_keyword_search`
83+
84+
Perform exact keyword searches with boolean operators and filters.
85+
86+
**Parameters:**
87+
- `query` - Search query with optional filters (required)
88+
89+
**Supported filters:**
90+
- `repo:` - limit to specific repositories
91+
- `file:` - search specific file patterns
92+
- `rev:` - search specific revisions
93+
94+
**Features:** Boolean AND/OR operators, regex patterns
95+
96+
#### `sg_nls_search`
97+
98+
Semantic search with flexible linguistic matching.
99+
100+
**Parameters:**
101+
- `query` - Natural language search query (required)
102+
103+
**Supported filters:**
104+
- `repo:` - limit to specific repositories
105+
- `file:` - search specific file patterns
106+
- `rev:` - search specific revisions
107+
108+
**Features:** Flexible linguistic matching, stemming, broader results than keyword search
109+
110+
### Code Navigation
111+
112+
#### `sg_go_to_definition`
113+
114+
Find the definition of a symbol from a usage location.
115+
116+
**Parameters:**
117+
- `repo` - Repository name (required)
118+
- `path` - File path containing symbol usage (required)
119+
- `symbol` - Symbol name to find definition for (required)
120+
- `revision` - Branch, tag, or commit hash (optional)
121+
122+
**Features:** Cross-repository support, compiler-level accuracy
123+
124+
#### `sg_find_references`
125+
126+
Find all references to a symbol from its definition location.
127+
128+
**Parameters:**
129+
- `repo` - Repository name (required)
130+
- `path` - File path containing symbol definition (required)
131+
- `symbol` - Symbol name to find references for (required)
132+
- `revision` - Branch, tag, or commit hash (optional)
133+
134+
### Version Control & History
135+
136+
#### `sg_commit_search`
137+
138+
Search commits by message, author, content, files, and date ranges.
139+
140+
**Parameters:**
141+
- `repos` - Array of repository names (required)
142+
- `messageTerms` - Terms to search in commit messages (optional)
143+
- `authors` - Filter by commit authors (optional)
144+
- `contentTerms` - Search in actual code changes (optional)
145+
- `files` - Filter by file paths (optional)
146+
- `after`/`before` - Date range filters (optional)
147+
148+
#### `sg_diff_search`
149+
150+
Search actual code changes for specific patterns across repositories.
151+
152+
**Parameters:**
153+
- `pattern` - Search pattern for code changes (required)
154+
- `repos` - Array of repository names (required)
155+
- `added` - Search only added code (optional)
156+
- `removed` - Search only removed code (optional)
157+
- `author` - Filter by author (optional)
158+
- `after`/`before` - Date range filters (optional)
159+
160+
#### `sg_compare_revisions`
161+
162+
Compare changes between two specific revisions.
163+
164+
**Parameters:**
165+
- `repo` - Repository name (required)
166+
- `base` - Base revision (older version) (required)
167+
- `head` - Head revision (newer version) (required)
168+
- `first` - Maximum file diffs to return (optional, default 50)
169+
- `after` - Pagination cursor (optional)
170+
171+
#### `sg_get_contributor_repos`
172+
173+
Find repositories where a contributor has made commits.
174+
175+
**Parameters:**
176+
- `author` - Author name or email (required)
177+
- `limit` - Maximum repositories to return (optional, default 20)
178+
- `minCommits` - Minimum commits required (optional, default 1)
179+
180+
### [Deep Search](/deep-search)
181+
182+
#### `sg_deepsearch`
183+
184+
Perform comprehensive analysis of complex questions about your codebase.
185+
186+
**Parameters:**
187+
- `question` - Complex technical question (required)
188+
189+
**Features:** Agentic LLM-powered research with automatic tool usage
190+
191+
## Usage Examples
192+
193+
### Finding Authentication Code
194+
195+
```json
196+
{
197+
"method": "tools/call",
198+
"params": {
199+
"name": "sg_nls_search",
200+
"arguments": {
201+
"query": "authentication login user"
202+
}
203+
}
204+
}
205+
```
206+
207+
### Reading a Specific File
208+
209+
```json
210+
{
211+
"method": "tools/call",
212+
"params": {
213+
"name": "sg_read_file",
214+
"arguments": {
215+
"repo": "github.com/myorg/myrepo",
216+
"path": "src/auth/login.go",
217+
"startLine": 1,
218+
"endLine": 50
219+
}
220+
}
221+
}
222+
```
223+
224+
### Finding Recent Changes
225+
226+
```json
227+
{
228+
"method": "tools/call",
229+
"params": {
230+
"name": "sg_commit_search",
231+
"arguments": {
232+
"repos": ["github.com/myorg/myrepo"],
233+
"messageTerms": ["bug fix"],
234+
"after": "1 week ago"
235+
}
236+
}
237+
}
238+
```
239+
240+
## Best Practices
241+
242+
1. **Repository Scoping:** Use `sg_list_repos` first to find relevant repositories for better performance
243+
2. **Progressive Search:** Start with broad searches (`sg_nls_search`) then narrow with specific tools
244+
3. **File Verification:** Use `sg_list_files` before `sg_read_file` to verify file existence
245+
4. **Pagination:** Use `after`/`before` cursors for large result sets
246+
5. **Tool Combinations:** Chain tools together (e.g., `sg_list_repos``sg_commit_search`)

src/data/navigation.ts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -531,6 +531,10 @@ export const navigation: NavigationItem[] = [
531531
{
532532
title: 'Sourcegraph Stream API',
533533
href: '/api/stream_api'
534+
},
535+
{
536+
title: 'Sourcegraph MCP Server',
537+
href: '/api/mcp'
534538
}
535539
]
536540
},

0 commit comments

Comments
 (0)