Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 11 additions & 24 deletions docs/streamable-http.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,27 +48,6 @@ github-mcp-server http --scope-challenge

When `--scope-challenge` is enabled, requests with insufficient scopes receive a `403 Forbidden` response with a `WWW-Authenticate` header indicating the required scopes.

### Repository deletion and request-state encryption

The `delete_repository` tool uses multi-round-trip elicitation and carries its
confirmed target through client-held request state. To expose this tool in HTTP
mode, configure a stable 32-byte encryption key encoded with standard Base64:

```bash
export GITHUB_MCP_SERVER_MRTR_STATE_KEY="$(openssl rand -base64 32 | tr -d '\n')"
github-mcp-server http
```

Use the same key on every replica that may handle a retry. Keep it secret and
stable during deployments; changing it invalidates confirmations already in
flight. If the variable is absent, `delete_repository` is not exposed by the
HTTP server. If it is present but malformed, the server refuses to start.

This self-hosted key is independent of keys used by the hosted remote server.
Integrators can provide their own request-state sealer through the exported
`github.RequestStateSealer` interface and expose it from their tool dependencies
through `github.RequestStateSealerProvider` without changing their key format.

### With OAuth Metadata Discovery

For use behind reverse proxies or with custom domains, expose OAuth metadata endpoints:
Expand Down Expand Up @@ -131,11 +110,19 @@ github-mcp-server http --trust-proxy-headers

Equivalent environment variable: `GITHUB_TRUST_PROXY_HEADERS=1`. Only enable this when the upstream proxy is trusted to set or strip these headers; otherwise prefer `--base-url`. When `--base-url` is set, it always takes precedence and `--trust-proxy-headers` has no effect.

### With an OAuth Proxy (GHES / non-standard authorization server)
### With an OAuth Proxy (GHES / RFC 7591 DCR clients)

When deploying against GitHub Enterprise Server, GHES does not natively support the OAuth extensions required by MCP (RFC 8414 metadata discovery, RFC 7591 Dynamic Client Registration, PKCE). Similarly, on `github.com`, `https://github.com/login/oauth` does not support RFC 7591 Dynamic Client Registration (`/register`) and returns `application/x-www-form-urlencoded` token responses unless `Accept: application/json` is sent—which prevents MCP clients that rely on DCR or standard OIDC refresh tokens (such as Google Gemini Web/Mobile custom apps or OpenCode) from completing automated OAuth onboarding.

When deploying against GitHub Enterprise Server, GHES does not natively support the OAuth extensions required by MCP (RFC 8414 metadata discovery, RFC 7591 Dynamic Client Registration, PKCE). In this case you can run a separate OAuth proxy that implements the MCP OAuth spec and forwards authentication to GHES. Use `--authorization-server` to advertise the proxy's URL in the protected resource metadata instead of the one derived from `--gh-host`:
In either case, you can run a separate OAuth 2.1 proxy that implements RFC 8414, RFC 7591 DCR, and JSON token exchange in front of GitHub's OAuth endpoints, and use `--authorization-server` to advertise the proxy's URL in the protected resource metadata instead of the default derived from `--gh-host`:

```bash
# Self-hosted github.com behind an OAuth 2.1 + DCR proxy
github-mcp-server http \
--base-url https://mcp.example.com \
--authorization-server https://mcp.example.com/oauth-proxy

# GitHub Enterprise Server behind an OAuth proxy
github-mcp-server http \
--gh-host https://github.example.com \
--base-url https://mcp.example.com \
Expand All @@ -156,7 +143,7 @@ The `authorization_servers` field in the protected resource metadata will then p

Equivalent environment variable: `GITHUB_AUTHORIZATION_SERVER=https://mcp.example.com/oauth-proxy`.

When neither the flag nor environment variable is set, the server preserves the existing behavior and derives the authorization server from `--gh-host`. The override only changes the URL advertised in OAuth protected resource metadata; it does not change token validation or the GitHub API host.
> **Note:** GitHub's hosted remote MCP endpoint (`https://api.githubcopilot.com/mcp/`) advertises `https://github.com/login/oauth` as its authorization server. Clients that require RFC 7591 Dynamic Client Registration against the hosted endpoint must connect through an external OAuth 2.1 + DCR proxy rather than directly to `api.githubcopilot.com`.

## Client Configuration

Expand Down