Skip to content

Commit f6daeef

Browse files
jamesmcnamarajamesmcnamara
committed
docs(sourcegraph): add docs for the MCP server
1 parent a4fa203 commit f6daeef

File tree

3 files changed

+278
-0
lines changed

3 files changed

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

‎src/data/navigation.ts‎

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

0 commit comments

Comments
 (0)