GitHub MCP Server: Poor authentication UX - 2 hours to fail

Summary

Spent 2 hours trying to configure the GitHub MCP server with Claude Code, ultimately unsuccessfully. The experience was frustrating and should be significantly improved.

Environment

• Windows 10/11
• Claude Code CLI
• GitHub CLI (gh) already authenticated and working
• gh auth status shows: Logged in as SHAI-LE with scopes: gist, read:org, repo, workflow

Expected Behavior

GitHub MCP server should either:

1. Automatically use existing gh CLI authentication (ideal)
2. Have clear, documented setup steps that work first time

Actual Experience

Problem 1: No integration with existing gh auth

• gh CLI was already authenticated with full repo permissions
• MCP server ignored this and required separate PAT configuration
• Users shouldn't need to manage two separate auth mechanisms for the same service

Problem 2: Unclear config file location

• Documentation unclear on where MCP settings should live
• Multiple potential locations: ~/.claude/settings.json, %APPDATA%/Claude/, etc.
• No way to verify which config file is being read
• No command like claude config show to see active MCP configuration

Problem 3: Unhelpful error messages

• First error: Authentication Failed: Requires authentication - doesn't say WHERE to configure
• After adding PAT: Authentication Failed: Bad credentials - doesn't say what's wrong with credentials
• No guidance on token format expected (ghp_ vs gho_ vs github_pat_)

Problem 4: OAuth token incompatibility

• gh auth login creates gho_ OAuth tokens
• MCP server apparently requires ghp_ PAT tokens
• This incompatibility is not documented anywhere
• Error message doesn't indicate this is the issue

Problem 5: No config validation

• After configuring PAT in config file, no way to test if config was read
• No feedback on whether MCP server loaded successfully
• Restart required but no confirmation it picked up new config

Steps Taken (all failed)

1. Verified gh CLI authenticated
2. Added PAT to config file as documented
3. Restarted Claude Code
4. Still got auth errors
5. Generated new PAT with correct scopes
6. Updated config, restarted
7. Still failing with "Bad credentials"

Suggestions for Improvement

1. Use existing gh auth: MCP server should read from gh auth token store (keyring) by default

1. Clear config location: Single, documented location with claude mcp config command to view/edit

1. Config validation: claude mcp test github command to verify authentication works

1. Better errors:

• "Token not found. Add GITHUB_PERSONAL_ACCESS_TOKEN to ~/.claude/mcp.json"
• "Token format invalid. Expected ghp_ PAT, got gho_ OAuth token"

1. Setup wizard: claude mcp setup github that walks through auth interactively

Impact

• 2 hours wasted on what should be 2-minute setup
• User gave up and cannot use GitHub MCP integration
• Poor first impression of Claude Code MCP ecosystem

---
Reported from Claude Code session.