Skip to content

Commit d322e26

Browse files
SamMorrowDrumsSamMorrowDrums
committed
feat: implement OAuth device flow authentication
When the server starts without a GITHUB_PERSONAL_ACCESS_TOKEN, it now starts in 'unauthenticated mode' with only an auth_login tool available. The auth_login tool: - Initiates the OAuth device flow with GitHub - Uses MCP URL elicitation to show the verification URL and user code - Polls for completion while showing progress notifications - Upon success, dynamically registers all configured GitHub tools This enables a much simpler setup experience - users no longer need to pre-configure a PAT. They can simply start the server and authenticate interactively when prompted. Key changes: - New AuthManager in pkg/github/auth.go handles device flow state - New auth_login tool in pkg/github/auth_tools.go - NewUnauthenticatedMCPServer in internal/ghmcp/server.go for token-less startup - CLI flags --oauth-client-id and --oauth-client-secret for enterprise scenarios - Support for github.com, GHES, and GHEC hosts The token is held in memory for the session duration - no persistent storage, which is ideal for Docker --rm workflows. Closes #132
1 parent 311d581 commit d322e26

File tree

8 files changed

+1416
-21
lines changed

8 files changed

+1416
-21
lines changed

‎cmd/github-mcp-server/main.go‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
package main
22

33
import (
4-
"errors"
54
"fmt"
65
"os"
76
"strings"
@@ -32,10 +31,8 @@ var (
3231
Short: "Start stdio server",
3332
Long: `Start a server that communicates via standard input/output streams using JSON-RPC messages.`,
3433
RunE: func(_ *cobra.Command, _ []string) error {
34+
// Token is optional - if not provided, server starts in auth mode
3535
token := viper.GetString("personal_access_token")
36-
if token == "" {
37-
return errors.New("GITHUB_PERSONAL_ACCESS_TOKEN not set")
38-
}
3936

4037
// If you're wondering why we're not using viper.GetStringSlice("toolsets"),
4138
// it's because viper doesn't handle comma-separated values correctly for env
@@ -84,6 +81,8 @@ var (
8481
ContentWindowSize: viper.GetInt("content-window-size"),
8582
LockdownMode: viper.GetBool("lockdown-mode"),
8683
RepoAccessCacheTTL: &ttl,
84+
OAuthClientID: viper.GetString("oauth-client-id"),
85+
OAuthClientSecret: viper.GetString("oauth-client-secret"),
8786
}
8887
return ghmcp.RunStdioServer(stdioServerConfig)
8988
},
@@ -109,6 +108,8 @@ func init() {
109108
rootCmd.PersistentFlags().Int("content-window-size", 5000, "Specify the content window size")
110109
rootCmd.PersistentFlags().Bool("lockdown-mode", false, "Enable lockdown mode")
111110
rootCmd.PersistentFlags().Duration("repo-access-cache-ttl", 5*time.Minute, "Override the repo access cache TTL (e.g. 1m, 0s to disable)")
111+
rootCmd.PersistentFlags().String("oauth-client-id", "", "OAuth App client ID for device flow authentication (optional, uses default if not provided)")
112+
rootCmd.PersistentFlags().String("oauth-client-secret", "", "OAuth App client secret for device flow authentication (optional, for confidential clients)")
112113

113114
// Bind flag to viper
114115
_ = viper.BindPFlag("toolsets", rootCmd.PersistentFlags().Lookup("toolsets"))
@@ -123,6 +124,8 @@ func init() {
123124
_ = viper.BindPFlag("content-window-size", rootCmd.PersistentFlags().Lookup("content-window-size"))
124125
_ = viper.BindPFlag("lockdown-mode", rootCmd.PersistentFlags().Lookup("lockdown-mode"))
125126
_ = viper.BindPFlag("repo-access-cache-ttl", rootCmd.PersistentFlags().Lookup("repo-access-cache-ttl"))
127+
_ = viper.BindPFlag("oauth-client-id", rootCmd.PersistentFlags().Lookup("oauth-client-id"))
128+
_ = viper.BindPFlag("oauth-client-secret", rootCmd.PersistentFlags().Lookup("oauth-client-secret"))
126129

127130
// Add subcommands
128131
rootCmd.AddCommand(stdioCmd)

‎docs/auth-design.md‎

Lines changed: 321 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,321 @@
1+
# OAuth Device Flow Authentication Design
2+
3+
## Overview
4+
5+
This document describes the implementation of OAuth Device Flow authentication for the GitHub MCP Server's stdio transport. The design enables users to authenticate without pre-configuring tokens, making setup significantly simpler.
6+
7+
## Problem Statement
8+
9+
Currently, users must:
10+
1. Generate a Personal Access Token (PAT) manually on GitHub
11+
2. Configure the token in their MCP host's configuration (often in plain text)
12+
3. Manage token rotation manually
13+
14+
This creates friction for new users and security concerns around token storage.
15+
16+
## Proposed Solution
17+
18+
When the server starts without a `GITHUB_PERSONAL_ACCESS_TOKEN`, instead of failing, it starts in "unauthenticated mode" with only authentication tools available. Users authenticate through MCP tool calls:
19+
20+
1. **`auth_login`** - Initiates device flow, returns verification URL and user code
21+
2. **`auth_verify`** - Completes the flow after user authorizes in browser
22+
23+
Once authenticated, the token is held in memory for the session and all regular tools become available.
24+
25+
## User Experience
26+
27+
### Before (Current)
28+
```jsonc
29+
{
30+
"githubz": {
31+
"command": "docker",
32+
"args": ["run", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
33+
"env": {
34+
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" // User must create PAT first
35+
}
36+
}
37+
}
38+
```
39+
40+
### After (New)
41+
```jsonc
42+
{
43+
"github": {
44+
"command": "docker",
45+
"args": ["run", "--rm", "-i", "ghcr.io/github/github-mcp-server", "stdio", "--toolsets=all"]
46+
// No token needed! User authenticates via tool call
47+
}
48+
}
49+
```
50+
51+
### Authentication Flow (User Perspective)
52+
53+
1. User asks agent: "Create an issue on my repo"
54+
2. Agent calls `auth_login` tool
55+
3. Tool returns:
56+
```
57+
To authenticate, visit: https://github.com/login/device
58+
Enter code: ABCD-1234
59+
60+
After authorizing, use the auth_verify tool to complete login.
61+
```
62+
4. User opens browser, enters code, clicks "Authorize"
63+
5. Agent calls `auth_verify` tool
64+
6. Tool returns: "Successfully authenticated as @username"
65+
7. Agent proceeds with original request using now-available tools
66+
67+
## Technical Design
68+
69+
### Architecture
70+
71+
```
72+
┌─────────────────────────────────────────────────────────────────┐
73+
│ MCP Server │
74+
├─────────────────────────────────────────────────────────────────┤
75+
│ │
76+
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
77+
│ │ Auth State │───▶│ Tool Filter │───▶│ GitHub Clients │ │
78+
│ │ Manager │ │ │ │ (lazy init) │ │
79+
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
80+
│ │ │ │
81+
│ │ token │ │
82+
│ ▼ ▼ │
83+
│ ┌──────────────┐ ┌──────────────────┐ │
84+
│ │ Device Flow │ │ REST/GraphQL │ │
85+
│ │ Handler │ │ Clients │ │
86+
│ └──────────────┘ └──────────────────┘ │
87+
│ │
88+
└─────────────────────────────────────────────────────────────────┘
89+
```
90+
91+
### State Machine
92+
93+
```
94+
┌─────────────────┐
95+
│ UNAUTHENTICATED │ ◀──────────────────────────────┐
96+
│ │ │
97+
│ Tools: auth_* │ │
98+
└────────┬────────┘ │
99+
│ auth_login() │
100+
▼ │
101+
┌─────────────────┐ │
102+
│ PENDING_AUTH │ │
103+
│ │──── timeout/error ─────────────▶│
104+
│ Tools: auth_* │ │
105+
└────────┬────────┘ │
106+
│ auth_verify() success │
107+
▼ │
108+
┌─────────────────┐ │
109+
│ AUTHENTICATED │ │
110+
│ │──── token invalid ─────────────▶│
111+
│ Tools: all │ │
112+
└─────────────────┘
113+
```
114+
115+
### Host URL Derivation
116+
117+
For different GitHub products, device flow endpoints are derived from the configured host:
118+
119+
| Product | Host Config | Device Code Endpoint |
120+
|---------|-------------|---------------------|
121+
| github.com | (default) | `https://github.com/login/device/code` |
122+
| GHEC | `https://tenant.ghe.com` | `https://tenant.ghe.com/login/device/code` |
123+
| GHES | `https://github.example.com` | `https://github.example.com/login/device/code` |
124+
125+
### OAuth App Requirements
126+
127+
The device flow requires an OAuth App. Options:
128+
1. **GitHub-provided OAuth App** (recommended) - We register a public OAuth App for this purpose
129+
2. **User-provided OAuth App** - Via `--oauth-client-id` flag for enterprise scenarios
130+
131+
Default OAuth App scopes (matching `gh` CLI minimal scopes):
132+
- `repo` - Full control of private repositories
133+
- `read:org` - Read org membership
134+
- `gist` - Create gists
135+
136+
### Key Components
137+
138+
#### 1. Auth State Manager (`pkg/github/auth_state.go`)
139+
140+
```go
141+
type AuthState struct {
142+
mu sync.RWMutex
143+
token string
144+
deviceCode *DeviceCodeResponse
145+
pollInterval time.Duration
146+
expiresAt time.Time
147+
}
148+
149+
func (a *AuthState) IsAuthenticated() bool
150+
func (a *AuthState) GetToken() string
151+
func (a *AuthState) StartDeviceFlow(ctx context.Context, host apiHost, clientID string) (*DeviceCodeResponse, error)
152+
func (a *AuthState) CompleteDeviceFlow(ctx context.Context) (string, error)
153+
```
154+
155+
#### 2. Auth Tools (`pkg/github/auth_tools.go`)
156+
157+
```go
158+
// auth_login tool - initiates device flow
159+
func AuthLogin(ctx context.Context) (*AuthLoginResult, error)
160+
161+
// auth_verify tool - completes device flow
162+
func AuthVerify(ctx context.Context) (*AuthVerifyResult, error)
163+
```
164+
165+
#### 3. Dynamic Tool Registration
166+
167+
When unauthenticated, only auth tools are registered. After successful auth:
168+
1. Initialize GitHub clients with new token
169+
2. Register all configured toolsets
170+
3. Send `tools/list_changed` notification to client
171+
172+
### Docker Considerations
173+
174+
With `--rm` containers:
175+
- Token lives only in memory for the session duration
176+
- User re-authenticates each time container starts
177+
- This is acceptable UX since device flow is quick (~30 seconds)
178+
179+
For persistent auth (optional future enhancement):
180+
- Mount a config volume: `-v ~/.config/github-mcp-server:/config`
181+
- Server stores encrypted token in volume
182+
- Requires user opt-in for security
183+
184+
### Security Considerations
185+
186+
1. **Token never in config** - Token obtained at runtime, never written to disk (in --rm mode)
187+
2. **Short-lived session** - Token only valid for container lifetime
188+
3. **Principle of least privilege** - Request minimal scopes
189+
4. **PKCE** - Use PKCE extension for additional security (if supported)
190+
5. **User verification** - User explicitly authorizes in browser with full visibility
191+
192+
### Error Handling
193+
194+
| Scenario | Behavior |
195+
|----------|----------|
196+
| Device flow timeout | Return error, user can retry `auth_login` |
197+
| User denies authorization | Return error explaining denial |
198+
| Network issues during poll | Retry with backoff, eventually timeout |
199+
| Invalid client ID | Clear error message with setup instructions |
200+
| Token expires mid-session | Return 401-like error, prompt re-auth via tools |
201+
202+
## Implementation Plan
203+
204+
### Phase 1: Core Auth Flow
205+
1. Add `pkg/github/auth_state.go` - Auth state management
206+
2. Add `pkg/github/auth_tools.go` - Auth tool implementations
207+
3. Modify `internal/ghmcp/server.go` - Support unauthenticated startup
208+
4. Add device flow endpoint derivation for all host types
209+
210+
### Phase 2: Dynamic Tool Registration
211+
1. Implement `tools/list_changed` notification after auth
212+
2. Add tool filtering based on auth state
213+
3. Update inventory to support dynamic registration
214+
215+
### Phase 3: Polish & Documentation
216+
1. Add comprehensive error messages
217+
2. Update README with new usage
218+
3. Add integration tests
219+
4. Document OAuth App setup for enterprises
220+
221+
## Usage Documentation
222+
223+
### Quick Start (New Users)
224+
225+
```jsonc
226+
// VS Code settings.json or mcp.json
227+
{
228+
"servers": {
229+
"github": {
230+
"command": "docker",
231+
"args": ["run", "--rm", "-i", "ghcr.io/github/github-mcp-server", "stdio"],
232+
"type": "stdio"
233+
}
234+
}
235+
}
236+
```
237+
238+
Then just ask your AI assistant to do something with GitHub - it will guide you through authentication!
239+
240+
### Native Installation
241+
242+
```bash
243+
# Install
244+
go install github.com/github/github-mcp-server/cmd/github-mcp-server@latest
245+
246+
# Run (will prompt for auth on first GitHub operation)
247+
github-mcp-server stdio
248+
```
249+
250+
### Enterprise (GHES/GHEC)
251+
252+
```jsonc
253+
{
254+
"servers": {
255+
"github": {
256+
"command": "github-mcp-server",
257+
"args": ["stdio", "--gh-host", "https://github.mycompany.com"],
258+
"type": "stdio"
259+
}
260+
}
261+
}
262+
```
263+
264+
### With Pre-configured Token (Legacy/CI)
265+
266+
```jsonc
267+
{
268+
"servers": {
269+
"github": {
270+
"command": "github-mcp-server",
271+
"args": ["stdio"],
272+
"env": {
273+
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
274+
},
275+
"type": "stdio"
276+
}
277+
}
278+
}
279+
```
280+
281+
## Open Questions
282+
283+
1. **OAuth App ownership** - Should GitHub provide a first-party OAuth App, or require users to create their own?
284+
2. **Token refresh** - Should we support refresh tokens for longer sessions, or is re-auth acceptable?
285+
3. **Scope customization** - Should users be able to request additional scopes via tool parameters?
286+
4. **Persistent storage** - Should we support optional persistent token storage for non-Docker installs?
287+
288+
## Appendix: Device Flow Sequence
289+
290+
```mermaid
291+
sequenceDiagram
292+
participant User
293+
participant Agent as AI Agent
294+
participant MCP as MCP Server
295+
participant GH as GitHub
296+
297+
User->>Agent: "Create issue on my repo"
298+
Agent->>MCP: tools/list
299+
MCP-->>Agent: [auth_login, auth_verify]
300+
301+
Agent->>MCP: tools/call auth_login
302+
MCP->>GH: POST /login/device/code
303+
GH-->>MCP: device_code, user_code, verification_uri
304+
MCP-->>Agent: "Visit github.com/login/device, enter ABCD-1234"
305+
306+
Agent->>User: "Please visit github.com/login/device and enter code ABCD-1234"
307+
User->>GH: Opens browser, enters code, authorizes
308+
309+
Agent->>MCP: tools/call auth_verify
310+
MCP->>GH: POST /login/oauth/access_token (polling)
311+
GH-->>MCP: access_token
312+
MCP->>MCP: Initialize GitHub clients
313+
MCP-->>Agent: notifications/tools/list_changed
314+
MCP-->>Agent: "Authenticated as @username"
315+
316+
Agent->>MCP: tools/list
317+
MCP-->>Agent: [all tools now available]
318+
Agent->>MCP: tools/call create_issue
319+
MCP-->>Agent: Issue created!
320+
Agent->>User: "Done! Created issue #123"
321+
```

0 commit comments

Comments
 (0)