Skip to content

streamable-http.md

Latest commit

 

History

History
105 lines (73 loc) · 3.67 KB

streamable-http.md

File metadata and controls

105 lines (73 loc) · 3.67 KB

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):

github-mcp-server http

The server will be available at http://localhost:8082.

With Scope Challenge

Enable scope validation to enforce GitHub permission checks:

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.

With OAuth Metadata Discovery

For use behind reverse proxies or with custom domains, expose OAuth metadata endpoints:

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:

{
  "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.

Behind a Trusted Proxy (advanced)

By default, the server ignores the X-Forwarded-Host and X-Forwarded-Proto headers when constructing OAuth resource metadata URLs, so an untrusted client cannot influence the URL advertised to MCP clients. For most deployments, setting --base-url to the externally visible URL is the right approach.

If the server sits behind an internal forwarder that you fully control (for example, an in-cluster gateway that needs to preserve the originating hostname per request), you can opt into honoring those headers:

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.

Client Configuration

Using OAuth Authentication

If your IDE or client has GitHub credentials configured (i.e. VS Code), simply reference the HTTP server:

{
  "type": "http",
  "url": "http://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:

{
  "type": "http",
  "url": "http://localhost:8082",
  "headers": {
    "Authorization": "Bearer ghp_yourtokenhere",
    "X-MCP-Toolsets": "default",
    "X-MCP-Readonly": "true"
  }
}

See Remote Server documentation for more details on client configuration options.