From 5384e2339e1af8443a7bd1ca40a889475e5705e1 Mon Sep 17 00:00:00 2001 From: Adam Holt Date: Fri, 6 Feb 2026 16:11:33 +0100 Subject: [PATCH 1/3] Add Streamable HTTP documentation --- docs/streamable-http.md | 93 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 docs/streamable-http.md diff --git a/docs/streamable-http.md b/docs/streamable-http.md new file mode 100644 index 000000000..229620f93 --- /dev/null +++ b/docs/streamable-http.md @@ -0,0 +1,93 @@ +# Streamable HTTP Server + +The Streamable HTTP mode enables the GitHub MCP Server to run as an HTTP service, allowing clients to connect via standard HTTP protocols. This mode is ideal for deployment scenarios where stdio transport isn't suitable, such as reverse proxy setups, containerized environments, or distributed architectures. + +## Features + +- **Streamable HTTP Transport** — Full HTTP server with streaming support for real-time tool responses +- **OAuth Metadata Endpoints** — Standard `.well-known/oauth-protected-resource` discovery for OAuth clients +- **Scope Challenge Support** — Automatic scope validation with proper HTTP 403 responses and `WWW-Authenticate` headers +- **Scope Filtering** — Restrict available tools based on authenticated credentials and permissions +- **Custom Base Paths** — Support for reverse proxy deployments with customizable base URLs + +## Running the Server + +### Basic HTTP Server + +Start the server on the default port (8082): + +```bash +github-mcp-server http +``` + +The server will be available at `http://localhost:8082`. + +### With Scope Challenge + +Enable scope validation to enforce GitHub permission checks: + +```bash +github-mcp-server http --port 80 --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. + +### With OAuth Metadata Discovery + +For use behind reverse proxies or with custom domains, expose OAuth metadata endpoints: + +```bash +github-mcp-server http --port 80 --scope-challenge --base-url https://myserver.com --base-path /mcp +``` + +The OAuth protected resource metadata's `resource` attribute will be populated with the full URL to the server's protected resource endpoint: + +```json +{ + "resource_name": "GitHub MCP Server", + "resource": "https://myserver.com/mcp", + "authorization_servers": [ + "https://github.com/login/oauth" + ], + "scopes_supported": [ + "repo", + ... + ], + ... +} +``` + +This allows OAuth clients to discover authentication requirements and endpoint information automatically. + +## Client Configuration + +### Using OAuth Authentication + +If your IDE or client has GitHub credentials configured (i.e. VSCode), simply reference the HTTP server: + +```json +{ + "type": "http", + "url": "https://localhost:8082" +} +``` + +The server will use the client's existing GitHub authentication. + +### Using Bearer Tokens or Custom Headers + +To provide PAT credentials, or to customize server behavior preferences, you can include additional headers in the client configuration: + +```json +{ + "type": "http", + "url": "https://localhost:8082", + "headers": { + "Authorization": "Bearer ghp_yourtokenhere", + "X-MCP-Toolsets": "default", + "X-MCP-Readonly": "true" + } +} +``` + +See [Remote Server](./remote-server.md) documentation for more details on client configuration options. From f5d86f0f9f702fafe2e4185bf9a103ad351c1e9e Mon Sep 17 00:00:00 2001 From: Adam Holt Date: Fri, 6 Feb 2026 17:35:46 +0100 Subject: [PATCH 2/3] Update docs/streamable-http.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/streamable-http.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/streamable-http.md b/docs/streamable-http.md index 229620f93..d904b4620 100644 --- a/docs/streamable-http.md +++ b/docs/streamable-http.md @@ -63,7 +63,7 @@ This allows OAuth clients to discover authentication requirements and endpoint i ### Using OAuth Authentication -If your IDE or client has GitHub credentials configured (i.e. VSCode), simply reference the HTTP server: +If your IDE or client has GitHub credentials configured (i.e. VS Code), simply reference the HTTP server: ```json { From 820345728ad50efc10192bb21fea8f37dc4702ce Mon Sep 17 00:00:00 2001 From: Adam Holt Date: Fri, 6 Feb 2026 17:38:01 +0100 Subject: [PATCH 3/3] Don't use privilaged ports or https for docs --- docs/streamable-http.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/streamable-http.md b/docs/streamable-http.md index d904b4620..0a11c5ea7 100644 --- a/docs/streamable-http.md +++ b/docs/streamable-http.md @@ -27,7 +27,7 @@ The server will be available at `http://localhost:8082`. Enable scope validation to enforce GitHub permission checks: ```bash -github-mcp-server http --port 80 --scope-challenge +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. @@ -37,7 +37,7 @@ When `--scope-challenge` is enabled, requests with insufficient scopes receive a For use behind reverse proxies or with custom domains, expose OAuth metadata endpoints: ```bash -github-mcp-server http --port 80 --scope-challenge --base-url https://myserver.com --base-path /mcp +github-mcp-server http --scope-challenge --base-url https://myserver.com --base-path /mcp ``` The OAuth protected resource metadata's `resource` attribute will be populated with the full URL to the server's protected resource endpoint: @@ -68,7 +68,7 @@ If your IDE or client has GitHub credentials configured (i.e. VS Code), simply r ```json { "type": "http", - "url": "https://localhost:8082" + "url": "http://localhost:8082" } ``` @@ -81,7 +81,7 @@ To provide PAT credentials, or to customize server behavior preferences, you can ```json { "type": "http", - "url": "https://localhost:8082", + "url": "http://localhost:8082", "headers": { "Authorization": "Bearer ghp_yourtokenhere", "X-MCP-Toolsets": "default",