Skip to content

docs(http): document --authorization-server for RFC 7591 DCR clients - #3847

Open
RealThanhNguyxn wants to merge 1 commit into
github:mainfrom
RealThanhNguyxn:docs/oauth-proxy-dcr-clarification
Open

RealThanhNguyxn wants to merge 1 commit into
github:mainfrom
RealThanhNguyxn:docs/oauth-proxy-dcr-clarification

Conversation

@RealThanhNguyxn

@RealThanhNguyxn RealThanhNguyxn commented Nov 14, 2026 •

Copy link
Copy Markdown

Summary

Clarifies docs/streamable-http.md to document using --authorization-server (GITHUB_AUTHORIZATION_SERVER) with an external OAuth 2.1 + Dynamic Client Registration (RFC 7591) proxy when self-hosting HTTP mode for MCP clients that require automated DCR and JSON token/refresh responses.

Related to #3519 and #2532.

Why

In addition to GitHub Enterprise Server deployments, https://github.com/login/oauth does not expose an RFC 7591 /register endpoint and returns application/x-www-form-urlencoded token payloads unless Accept: application/json is supplied. MCP clients that rely on RFC 7591 DCR or standard OIDC refresh tokens (such as Google Gemini Web/Mobile custom apps or OpenCode) cannot complete automated OAuth discovery against github.com/login/oauth directly.

github-mcp-server http already supports --authorization-server to advertise an OAuth proxy in /.well-known/oauth-protected-resource, so documenting this use case alongside GHES—and noting that the hosted api.githubcopilot.com/mcp/ endpoint requires an external OAuth proxy for DCR clients—gives operators a clear, supported configuration path.

What changed

  • Expanded With an OAuth Proxy in docs/streamable-http.md to cover self-hosted github.com deployments behind an OAuth 2.1 + DCR proxy in addition to GHES.
  • Added a self-hosted github.com CLI example using --base-url and --authorization-server.
  • Added a note clarifying that https://api.githubcopilot.com/mcp/ advertises https://github.com/login/oauth directly and requires an external OAuth proxy for RFC 7591 DCR clients.

MCP impact

  • No tool or API changes
  • Tool schema or behavior changed
  • New tool added

Prompts tested (tool changes only)

  • N/A (documentation-only change)

Security / limits

  • No security or limits impact
  • Auth / permissions considered — clarifies the boundary between the MCP protected resource (/.well-known/oauth-protected-resource) and external OAuth 2.1 authorization proxies; no runtime auth logic changed.
  • Data exposure, filtering, or token/size limits considered

Tool renaming

  • I am renaming tools as part of this PR (e.g. a part of a consolidation effort)
    • I have added the new tool aliases in deprecated_tool_aliases.go
  • I am not renaming tools as part of this PR

Lint & tests

  • Linted locally with ./script/lint
  • Tested locally with ./script/test
  • Documentation-only change in docs/streamable-http.md. Both scripts ran locally: ./script/lint reports 0 issues and ./script/test (go test -race ./...) passes across all packages.

Docs

  • Not needed
  • Updated (README / docs / examples)

@RealThanhNguyxn
RealThanhNguyxn requested a review from a team as a code owner November 14, 2026 04:04
Copilot AI adaptive review requested due to automatic review settings November 14, 2026 04:04

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The change removes the only documentation for configuring request-state encryption and the related deployment requirement, while the server behavior and tests still depend on it.

1 open issue
What changed in this PR

Updates Streamable HTTP documentation to explain configuring external OAuth 2.1 / RFC 7591 Dynamic Client Registration proxies for GitHub.com and GHES deployments, including limitations of the hosted MCP endpoint.

Changes:

  • Documents --authorization-server and GITHUB_AUTHORIZATION_SERVER proxy configuration.
  • Adds a self-hosted GitHub.com example and hosted endpoint guidance for DCR-dependent clients.
  • Removes the existing request-state encryption and delete_repository configuration documentation.
File Description
docs/​streamable-http.md Expands OAuth proxy guidance with GitHub.com examples and hosted endpoint limitations while modifying adjacent HTTP deployment and request-state encryption documentation.

Review effort: Lite (dynamic)

Comment thread docs/streamable-http.md
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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants