GitHub MCP Server 如何启动 Streamable HTTP 服务器并配置 base-url 与 scope-challenge？

如果你的 MCP 客户端无法通过 stdio 传输连接 GitHub MCP Server（例如需要走反向代理、容器化部署或分布式架构），就需要把它以 Streamable HTTP 模式跑起来。这篇文档给出的完整路径是：用 github-mcp-server http 启动默认 8082 端口的 HTTP 服务；通过 --base-url 和 --base-path 让 OAuth 资源元数据指向对外可见的地址；用 --scope-challenge 开启 scope 校验，使权限不足的请求返回带 WWW-Authenticate 头的 403 响应。以下内容来自 Streamable HTTP 文档。

准备条件

• 本机可执行 github-mcp-server 二进制。按 README 的说明，可以用 go build 在 cmd/github-mcp-server 目录下构建，也可以使用公开的 Docker 镜像 ghcr.io/github/github-mcp-server。
• 认证凭据。服务器本身不内置凭据：客户端可以用 OAuth（如 VS Code 这类已配置 GitHub 凭据的主机），也可以在客户端配置里传 PAT 的 Authorization 头。

启动默认的 Streamable HTTP 服务器

最基本的启动命令：

github-mcp-server http

服务器会在默认端口 8082 上监听，启动后可通过 http://localhost:8082 访问。这就是验证服务是否起来的直接依据：客户端或浏览器应能连到该地址。

开启 scope-challenge

在启动命令上加 --scope-challenge 参数：

github-mcp-server http --scope-challenge

启用后，携带权限（scope）不足的请求会收到 403 Forbidden 响应，并且响应头中的 WWW-Authenticate 会指明所需的 scope。这是 scope-challenge 生效的判断方式：用 scope 不足的凭据发起一次请求，如果看到 403 加 WWW-Authenticate 头，说明校验已启用；正常权限的请求则照常通过。

scope 在不同认证方式下的行为差异，参见 Scope Filtering 文档：classic PAT 在启动时按 token scope 过滤工具，OAuth 则按需发起 scope challenge。

配置 base-url 与 base-path

当服务器部署在反向代理后面或使用自定义域名时，需要让 OAuth 元数据指向客户端实际访问的地址。文档给出的完整示例（其中 https://myserver.com 和 /mcp 应替换为你自己的对外地址与路径）：

github-mcp-server http --scope-challenge --base-url https://myserver.com --base-path /mcp

• --base-url：服务器对外可访问的基础 URL，用于填充 OAuth 资源元数据。
• --base-path：对外可见的基础路径，同样用于元数据。

设置后，OAuth protected resource 元数据中的 resource 属性会被填充为服务器受保护资源端点的完整 URL。文档示例（示例结果，实际值取决于你配置的地址）：

{
  "resource_name": "GitHub MCP Server",
  "resource": "https://myserver.com/mcp",
  "authorization_servers": [
    "https://github.com/login/oauth"
  ],
  "scopes_supported": [
    "repo",
    "..."
  ]
}

这样 OAuth 客户端就能自动发现认证要求和端点信息。验证方式是请求 /.well-known/oauth-protected-resource 端点，确认 resource 字段的值与你配置的 --base-url / --base-path 拼出的 URL 一致。

两点行为边界需要注意：

1. 该 HTTP 服务器本身是 OAuth protected resource，不是 authorization server。因此它会提供 /.well-known/oauth-protected-resource，但不会提供 /.well-known/oauth-authorization-server，除非你在同一 origin 上显式托管了一个独立部署的授权服务器。
2. 默认情况下服务器会忽略 X-Forwarded-Host 和 X-Forwarded-Proto 头来构造 OAuth 资源元数据 URL，防止不受信任的客户端影响对外通告的地址。对大多数部署，直接设置 --base-url 为对外可见 URL 是正确做法。只有当服务器位于你完全控制的内部转发器后面时，才考虑：

github-mcp-server http --trust-proxy-headers

等价环境变量为 GITHUB_TRUST_PROXY_HEADERS=1。仅当上游代理可信时才启用；且当 --base-url 已设置时，它始终优先，--trust-proxy-headers 不生效。

可选分支

对接 GHES 的 OAuth 代理。 面向 GitHub Enterprise Server 部署时，GHES 原生不支持 MCP 所需的 OAuth 扩展（RFC 8414 元数据发现、RFC 7591 动态客户端注册、PKCE）。此时需要单独运行一个实现 MCP OAuth 规范并转发认证到 GHES 的代理，并用 --authorization-server 在元数据中通告代理地址：

github-mcp-server http \
  --gh-host https://github.example.com \
  --base-url https://mcp.example.com \
  --authorization-server https://mcp.example.com/oauth-proxy

此时元数据中的 authorization_servers 字段指向你的代理。等价环境变量为 GITHUB_AUTHORIZATION_SERVER。注意该覆盖只改变元数据中通告的 URL，不改变 token 校验或 GitHub API host。

暴露 delete_repository 工具。 该工具依赖多轮 elicitation 和客户端持有的请求状态，需要配置一个稳定的 32 字节、标准 Base64 编码的加密密钥：

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

所有可能处理重试的副本必须使用同一把密钥；部署期间保持密钥保密且稳定，更换会使已进行中的确认失效。该变量缺失时 delete_repository 不会被 HTTP 服务器暴露；变量存在但格式错误时服务器拒绝启动。

客户端接入与验证

服务器起来后，在 MCP 客户端中引用 HTTP 地址。使用 OAuth 认证的客户端（例如 VS Code）只需：

{
  "type": "http",
  "url": "http://localhost:8082"
}

若要用 PAT 或定制行为，则在客户端配置中加入请求头（ghp_yourtokenhere 替换为你自己的 PAT）：

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

X-MCP-Toolsets、X-MCP-Tools、X-MCP-Readonly 等可选请求头的含义与取值规则见 Remote Server 文档 的 Optional Headers 一节。

整条路径的验证顺序：确认服务在 8082 端口可达；请求 /.well-known/oauth-protected-resource 核对 resource 是否反映了 --base-url / --base-path 配置；用 scope 不足的凭据发请求，确认返回 403 且 WWW-Authenticate 头列出了所需 scope；最后在客户端完成工具调用。若发现工具按 scope 隐藏或可见性不符合预期，按 Scope Filtering 文档 中的排查表对照 token 类型与日志检查。