Skip to content

Commit 7204a63

Browse files
tommaso-morotommaso-moro
committed
add server configuration guide
1 parent 303b2ad commit 7204a63

File tree

3 files changed

+357
-0
lines changed

3 files changed

+357
-0
lines changed

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -328,6 +328,8 @@ _Toolsets are not limited to Tools. Relevant MCP Resources and Prompts are also
328328

329329
When no toolsets are specified, [default toolsets](#default-toolset) are used.
330330

331+
> **Looking for examples?** See the [Server Configuration Guide](https://github.com/github/github-mcp-server/tree/main/docs/server-configuration.md) for common recipes like minimal setups, read-only mode, and combining tools with toolsets.
332+
331333
#### Specifying Toolsets
332334

333335
To specify toolsets you want available to the LLM, you can pass an allow-list in two ways:

‎docs/remote-server.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,8 @@ The Remote GitHub MCP server has optional headers equivalent to the Local server
6868
- Equivalent to `GITHUB_LOCKDOWN_MODE` env var for Local server.
6969
- If this header is empty, "false", "f", "no", "n", "0", or "off" (ignoring whitespace and case), it will be interpreted as false. All other values are interpreted as true.
7070

71+
> **Looking for examples?** See the [Server Configuration Guide](https://github.com/github/github-mcp-server/tree/main/docs/server-configuration.md) for common recipes like minimal setups, read-only mode, and combining tools with toolsets.
72+
7173
Example:
7274

7375
```json

‎docs/server-configuration.md‎

Lines changed: 353 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,353 @@
1+
# Server Configuration Guide
2+
3+
This guide helps you choose the right configuration for your use case and shows you how to apply it. For the complete reference of available toolsets and tools, see the [README](https://github.com/github/github-mcp-server?tab=readme-ov-file#tool-configuration).
4+
5+
## Quick Reference
6+
We currently support the following ways in which the GitHub MCP Server can be configured:
7+
8+
| Configuration | Remote Server | Local Server |
9+
|---------------|---------------|--------------|
10+
| Toolsets | `X-MCP-Toolsets` header or `/x/{toolset}` URL | `--toolsets` flag or `GITHUB_TOOLSETS` env var |
11+
| Individual Tools | `X-MCP-Tools` header | `--tools` flag or `GITHUB_TOOLS` env var |
12+
| Read-Only Mode | `X-MCP-Readonly` header or `/readonly` URL | `--read-only` flag or `GITHUB_READ_ONLY` env var |
13+
| Dynamic Mode | Not available | `--dynamic-toolsets` flag or `GITHUB_DYNAMIC_TOOLSETS` env var |
14+
| Lockdown Mode | `X-MCP-Lockdown` header | `--lockdown-mode` flag or `GITHUB_LOCKDOWN_MODE` env var |
15+
16+
> **Default behavior:** If you don't specify any configuration, the server uses the **default toolsets**: `context`, `issues`, `pull_requests`, `repos`, `users`.
17+
18+
---
19+
20+
## How Configuration Works
21+
22+
All configuration options are **composable**: you can combine toolsets, individual tools, dynamic discovery, read-only mode and lockdown mode in any way that suits your workflow.
23+
24+
For example:
25+
- **Tools + Toolsets**: The server enables the union of both
26+
- **Dynamic mode + Tools**: Start minimal with the tools you know you need, and discover more toolsets on demand
27+
- **Read-Only Mode**: Acts as a strict security filter that takes precedence over any other configuration, by disabling write tools are excluded even if explicitly requested
28+
29+
---
30+
31+
## Configuration Examples
32+
33+
The examples below use VS Code configuration format to illustrate the concepts. If you're using a different MCP host (Cursor, Claude Desktop, JetBrains, etc.), your configuration might need to look slightly different. See [installation guides](https://github.com/github/github-mcp-server/tree/main/docs/installation-guides) for host-specific setup.
34+
35+
### Enabling Specific Tools
36+
37+
**Best for:** users who know exactly what they need and want to optimize context usage by loading only the tools they will use.
38+
39+
**Example:**
40+
41+
<table>
42+
<tr><th>Remote Server</th><th>Local Server</th></tr>
43+
<tr valign="top">
44+
<td>
45+
46+
```json
47+
{
48+
"type": "http",
49+
"url": "https://api.githubcopilot.com/mcp/",
50+
"headers": {
51+
"X-MCP-Tools": "get_file_contents,get_me,pull_request_read"
52+
}
53+
}
54+
```
55+
56+
</td>
57+
<td>
58+
59+
```json
60+
{
61+
"type": "stdio",
62+
"command": "go",
63+
"args": [
64+
"run",
65+
"./cmd/github-mcp-server",
66+
"stdio",
67+
"--tools=get_file_contents,get_me,pull_request_read"
68+
],
69+
"env": {
70+
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
71+
}
72+
}
73+
```
74+
75+
</td>
76+
</tr>
77+
</table>
78+
79+
---
80+
81+
### Enabling Specific Toolsets
82+
83+
**Best for:** Users who want to enable multiple related toolsets.
84+
85+
<table>
86+
<tr><th>Remote Server</th><th>Local Server</th></tr>
87+
<tr valign="top">
88+
<td>
89+
90+
```json
91+
{
92+
"type": "http",
93+
"url": "https://api.githubcopilot.com/mcp/",
94+
"headers": {
95+
"X-MCP-Toolsets": "issues,pull_requests"
96+
}
97+
}
98+
```
99+
100+
</td>
101+
<td>
102+
103+
```json
104+
{
105+
"type": "stdio",
106+
"command": "go",
107+
"args": [
108+
"run",
109+
"./cmd/github-mcp-server",
110+
"stdio",
111+
"--toolsets=issues,pull_requests"
112+
],
113+
"env": {
114+
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
115+
}
116+
}
117+
```
118+
119+
</td>
120+
</tr>
121+
</table>
122+
123+
---
124+
125+
### Enabling Toolsets + Tools
126+
127+
**Best for:** Users who want broad functionality from some areas, plus specific tools from others.
128+
129+
Enable entire toolsets, then add individual tools from toolsets you don't want fully enabled.
130+
131+
<table>
132+
<tr><th>Remote Server</th><th>Local Server</th></tr>
133+
<tr valign="top">
134+
<td>
135+
136+
```json
137+
{
138+
"type": "http",
139+
"url": "https://api.githubcopilot.com/mcp/",
140+
"headers": {
141+
"X-MCP-Toolsets": "repos,issues",
142+
"X-MCP-Tools": "get_gist,pull_request_read"
143+
}
144+
}
145+
```
146+
147+
</td>
148+
<td>
149+
150+
```json
151+
{
152+
"type": "stdio",
153+
"command": "go",
154+
"args": [
155+
"run",
156+
"./cmd/github-mcp-server",
157+
"stdio",
158+
"--toolsets=repos,issues",
159+
"--tools=get_gist,pull_request_read"
160+
],
161+
"env": {
162+
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
163+
}
164+
}
165+
```
166+
167+
</td>
168+
</tr>
169+
</table>
170+
171+
**Result:** All repository and issue tools, plus just the gist tools you need.
172+
173+
---
174+
175+
### Read-Only Mode
176+
177+
**Best for:** Security conscious users that want to ensure the server won't allow operations that modify issues, pull requests, repositories etc.
178+
179+
When active, this mode will disable all tools that are not read-only even if they were requested.
180+
181+
**Example:**
182+
<table>
183+
<tr><th>Remote Server</th><th>Local Server</th></tr>
184+
<tr valign="top">
185+
<td>
186+
187+
**Option A: Header**
188+
```json
189+
{
190+
"type": "http",
191+
"url": "https://api.githubcopilot.com/mcp/",
192+
"headers": {
193+
"X-MCP-Toolsets": "issues,repos,pull_requests",
194+
"X-MCP-Readonly": "true"
195+
}
196+
}
197+
```
198+
199+
**Option B: URL path**
200+
```json
201+
{
202+
"type": "http",
203+
"url": "https://api.githubcopilot.com/mcp/x/all/readonly"
204+
}
205+
```
206+
207+
</td>
208+
<td>
209+
210+
211+
```json
212+
{
213+
"type": "stdio",
214+
"command": "go",
215+
"args": [
216+
"run",
217+
"./cmd/github-mcp-server",
218+
"stdio",
219+
"--toolsets=issues,repos,pull_requests",
220+
"--read-only"
221+
],
222+
"env": {
223+
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
224+
}
225+
}
226+
```
227+
228+
</td>
229+
</tr>
230+
</table>
231+
232+
> Even if `issues` toolset contains `create_issue`, it will be excluded in read-only mode.
233+
234+
---
235+
236+
### Dynamic Discovery (Local Only)
237+
238+
**Best for:** Letting the LLM discover and enable toolsets as needed.
239+
240+
Starts with only discovery tools (`enable_toolset`, `list_available_toolsets`, `get_toolset_tools`), then expands on demand.
241+
242+
<table>
243+
<tr><th>Local Server Only</th></tr>
244+
<tr valign="top">
245+
<td>
246+
247+
```json
248+
{
249+
"type": "stdio",
250+
"command": "go",
251+
"args": [
252+
"run",
253+
"./cmd/github-mcp-server",
254+
"stdio",
255+
"--dynamic-toolsets"
256+
],
257+
"env": {
258+
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
259+
}
260+
}
261+
```
262+
263+
**With some tools pre-enabled:**
264+
```json
265+
{
266+
"type": "stdio",
267+
"command": "go",
268+
"args": [
269+
"run",
270+
"./cmd/github-mcp-server",
271+
"stdio",
272+
"--dynamic-toolsets",
273+
"--tools=get_me,search_code"
274+
],
275+
"env": {
276+
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
277+
}
278+
}
279+
```
280+
281+
</td>
282+
</tr>
283+
</table>
284+
285+
When both dynamic mode and specific tools are enabled in the server configuration, the server will start with the 3 dynamic tools + the specified tools.
286+
287+
---
288+
289+
### Lockdown Mode
290+
291+
**Best for:** Public repositories where you want to limit content from users without push access.
292+
293+
Lockdown mode ensures the server only surfaces content in public repositories from users with push access to that repository. Private repositories are unaffected, and collaborators retain full access to their own content.
294+
295+
**Example:**
296+
<table>
297+
<tr><th>Remote Server</th><th>Local Server</th></tr>
298+
<tr valign="top">
299+
<td>
300+
301+
```json
302+
{
303+
"type": "http",
304+
"url": "https://api.githubcopilot.com/mcp/",
305+
"headers": {
306+
"X-MCP-Lockdown": "true"
307+
}
308+
}
309+
```
310+
311+
</td>
312+
<td>
313+
314+
```json
315+
{
316+
"type": "stdio",
317+
"command": "go",
318+
"args": [
319+
"run",
320+
"./cmd/github-mcp-server",
321+
"stdio",
322+
"--lockdown-mode"
323+
],
324+
"env": {
325+
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
326+
}
327+
}
328+
```
329+
330+
</td>
331+
</tr>
332+
</table>
333+
334+
---
335+
336+
## Troubleshooting
337+
338+
| Problem | Cause | Solution |
339+
|---------|-------|----------|
340+
| Server fails to start | Invalid tool name in `--tools` or `X-MCP-Tools` | Check tool name spelling; use exact names from [Tools list](https://github.com/github/github-mcp-server?tab=readme-ov-file#tools) |
341+
| Write tools not working | Read-only mode enabled | Remove `--read-only` flag or `X-MCP-Readonly` header |
342+
| Tools missing | Toolset not enabled | Add the required toolset or specific tool |
343+
| Dynamic tools not available | Using remote server | Dynamic mode is available in the local MCP server only |
344+
345+
---
346+
347+
## Useful links
348+
349+
- [README: Tool Configuration](https://github.com/github/github-mcp-server?tab=readme-ov-file#tool-configuration) — Full reference for toolsets, tools, and flags
350+
- [README: Available Toolsets](https://github.com/github/github-mcp-server?tab=readme-ov-file#available-toolsets) — Complete list of toolsets
351+
- [README: Tools](https://github.com/github/github-mcp-server?tab=readme-ov-file#tools) — Complete list of individual tools
352+
- [Remote Server Documentation](https://github.com/github/github-mcp-server/blob/main/docs/remote-server.md) — Remote-specific options and headers
353+
- [Installation Guides](https://github.com/github/github-mcp-server/tree/main/docs/installation-guides) — Host-specific setup instructions

0 commit comments

Comments
 (0)