hermes - 💡(How to fix) Fix GitHub MCP OAuth: standard PKCE flow doesn't work, device code flow is fragile workaround

The Problem

Setting up the GitHub MCP server (https://api.githubcopilot.com/mcp/) is currently a manual, fragile process.

Why Standard MCP OAuth (PKCE) Fails

The GitHub MCP server returns WWW-Authenticate: Bearer with resource_metadata pointing to authorization_servers: ["https://github.com/login/oauth"]. However:

1. /.well-known/oauth-authorization-server returns 404 — no standard OAuth metadata
2. /.well-known/openid-configuration does respond, but:
3. No dynamic client registration endpoint exists — you can't programmatically register a client
4. The only known client IDs only support device code flow — redirect URIs are NOT registered, so PKCE can't redirect back

Hermes' MCP client (tools/mcp_oauth.py + tools/mcp_oauth_manager.py) currently tries standard PKCE/OAuth discovery, hits the 404 on oauth-authorization-server, and falls over. It doesn't gracefully handle the openid-configuration path or fall back to device code flow when PKCE is impossible.

The Workaround (Device Code Flow)

Until Hermes supports proper OAuth for this server, the only working approach is GitHub OAuth device code grant:

POST https://github.com/login/device/code   → get device_code + user_code
User opens https://github.com/login/device   → enters user_code, clicks Authorize
POST https://github.com/login/oauth/access_token → get access_token

Then manually write the token as a static Authorization: Bearer *** header in config.yaml under mcp_servers.github.

This is fragile — the gho_* token expires in ~8h with no refresh, and each re-auth requires the whole flow again.

What a Proper Solution Would Look Like

Implement proper OAuth support in Hermes' MCP client by handling /.well-known/openid-configuration discovery as a fallback when oauth-authorization-server returns 404. The OpenID config does give valid token/authorization endpoints.

Register an official Hermes GitHub OAuth app (like VS Code, JetBrains, and other agents do) so users don't have to create their own. This app should have:

• A registered redirect URI for PKCE (http://localhost or a Hermes-specific callback)
• Proper scopes configured (repo, read:user, workflow, admin:org)

A user from the community has already created a working OAuth app and tested the device code flow end-to-end — detailed in the technical reference below. The auth mechanism and endpoints are validated; what's missing is the Hermes-side integration to handle it automatically via the standard OAuth discovery path.

Full Technical Reference

• Device code endpoint: POST https://github.com/login/device/code (params: client_id, scope)
• Token endpoint: POST https://github.com/login/oauth/access_token (params: client_id, device_code, grant_type)
• Grant type: urn:ietf:params:oauth:grant-type:device_code
• OpenID configuration: GET https://github.com/.well-known/openid-configuration (returns valid token/authorization endpoints)
• OAuth authorization server: GET https://github.com/.well-known/oauth-authorization-server (returns 404!)
• Copilot exchange: GET https://api.github.com/copilot_internal/v2/token (header: Authorization: token <gho_*>) — returns 404 without Copilot sub
• Minimum working scopes: repo,read:user,workflow,admin:org
• Token format: gho_* (raw OAuth) or Copilot API token (with paid sub)
• Hermes source: tools/mcp_oauth.py (PKCE attempt), tools/mcp_oauth_manager.py (OAuth state), hermes_cli/copilot_auth.py (has working device code login code)