企业官网建设流程全解析

如何为 MCP Toolbox 启用 MCP Authorization（OAuth 2.1）并配置 TOOLBOX_URL 与 PRM 端点

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox

如果你的 MCP Toolbox 部署后要暴露给其他团队的 MCP 客户端（例如 Claude Desktop、Gemini CLI 或自研 Agent），直接开放/mcp端点意味着任何人都能调用你的工具。MCP Toolbox 提供了 MCP Authorization：它以 OAuth 2.1 资源服务器（Resource Server）的身份校验客户端携带的 JWT Bearer 令牌，并自动发布/.well-known/oauth-protected-resource这个 Protected Resource Metadata（PRM）端点，让客户端能自行发现授权服务器并发起授权流程。完成本文后，你的 Toolbox 会拦截/mcp路由上的请求，只有携带由你的 OIDC 授权服务器签发、aud与 scope 均合法的令牌的客户端才能进入，而客户端能通过 PRM 端点自动拿到授权所需信息。

前提与工作方式

• MCP Authorization 模式目前仅支持generic类型的 auth service（见 Authentication 总览）。
• 启用后，Toolbox 会从authorizationServer拉取 JWKS（JSON Web Key Set），对每个请求做签名、过期时间（exp）、受众（aud）和 scope 校验；opaque 令牌则走 introspection 端点（详见 Generic OIDC Auth）。
• 令牌通过标准Authorization: Bearer <token>请求头传入，而非 Toolbox 原生鉴权使用的<name>_token自定义头。

第一步：在 tools.yaml 中配置 generic Auth Service

在tools.yaml顶层添加一个type: generic的authService，并设置mcpEnabled: true。mcpEnabled: true会让 Toolbox 拦截/mcp路由上的请求校验 Bearer 令牌，同时自动基于authorizationServer发布 PRM 端点：

kind: authService name: my-mcp-auth type: generic mcpEnabled: true authorizationServer: "https://accounts.google.com" # Your authorization server URL audience: "your-mcp-audience" # Matches the `aud` claim in the JWT scopesRequired: - "mcp:tools"

需要替换的字段：

• authorizationServer：你的 OIDC 提供方基础 URL，Toolbox 会追加/.well-known/openid-configuration来发现 JWKS；
• audience：令牌中audclaim 的期望值，即签发令牌时指定的受众；
• scopesRequired：令牌scopeclaim 中必须包含的 scope 列表。

警告（来自 Generic OIDC Auth 文档）：不要用type: generic配置 Google 的 tokeninfo 端点（https://oauth2.googleapis.com/tokeninfo），因为 generic 服务会强制校验 RFC 7662 的activeclaim，而 Google tokeninfo 不返回该 claim，校验会失败。Google 令牌应使用type: google的原生服务。

第二步：配置 TOOLBOX_URL 并部署

部署带 MCP auth 的 Toolbox 时必须定义一个绝对 URL（包含 scheme 和 host，例如https://my-toolbox.example.com），因为该 URL 会作为resource字段写入返回给客户端的 PRM。可以设置TOOLBOX_URL环境变量，或使用--toolbox-url命令行参数，两者等价（参数定义见 CLI 参考，--toolbox-url在缺省时回落到TOOLBOX_URL环境变量）。

本地部署（主路径）

在运行二进制文件前导出TOOLBOX_URL，指向本地端口：

export TOOLBOX_URL="http://127.0.0.1:5000" ./toolbox --tools-file tools.yaml

或者显式使用--toolbox-url参数：

./toolbox --tools-file tools.yaml --toolbox-url "http://127.0.0.1:5000"

Cloud Run 部署（可选分支）

如果你要把服务发布到 Google Cloud Run，用gcloud run deploy把目标 Cloud Run URL 通过--toolbox-url传入。注意该命令会实际部署/更新一个 Cloud Run 服务并绑定 Secret，执行前确认项目、区域与镜像正确：

export IMAGE="us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest" # Pass your target Cloud Run URL to the `--toolbox-url` flag gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080","--toolbox-url=${CLOUD_RUN_TOOLBOX_URL}"

可选：用 --mcp-prm-file 手动覆盖 PRM

如果不想让 Toolbox 从AuthService配置自动生成 PRM，而要严格自定义 Protected Resource Metadata，可以用--mcp-prm-file <path>参数提供一份 RFC-9207 兼容的prm.json。注意其中resource字段必须与TOOLBOX_URL一致：

{ "resource": "https://toolbox-service-123456789-uc.a.run.app", "authorization_servers": ["https://your-auth-server.example.com"], "scopes_supported": ["mcp:tools"], "bearer_methods_supported": ["header"] }

本地部署直接传文件路径：

./toolbox --tools-file tools.yaml --mcp-prm-file prm.json

Cloud Run 场景需要先把文件上传到 Secret Manager 再挂载到部署中（该命令会创建 Secret 并部署服务，注意副作用）：

gcloud secrets create prm_file --data-file=prm.json gcloud run deploy toolbox \ # ... previous args --set-secrets "/app/tools.yaml=tools:latest,/app/prm.json=prm_file:latest" \ --args="--tools-file=/app/tools.yaml","--mcp-prm-file=/app/prm.json","--port=8080"

验证 PRM 端点已生效

服务启动后，在浏览器或客户端请求TOOLBOX_URL对应的/.well-known/oauth-protected-resource路径，应当能看到 PRM 的 JSON 内容。例如TOOLBOX_URL为https://my-toolbox.example.com时，访问https://my-toolbox.example.com/.well-known/oauth-protected-resource。下面是 Looker + Claude Desktop 集成示例中浏览器查看 PRM 的文档示例（文档示例，数值和域名以你实际部署为准）：

客户端连接与令牌校验结果

部署完成后，MCP 客户端必须先从你在tools.yaml中配置的授权服务器获取合法的 JWT，然后通过标准Authorization头把它带给 Streamable HTTP 或 SSE 端点/mcp。MCP Auth 文档给出的客户端配置示例如下（将<your-jwt-access-token>替换为你从授权服务器实际取得的 JWT）：

{ "mcpServers": { "toolbox-secure": { "type": "http", "url": "https://toolbox-service-123456789-uc.a.run.app/mcp", "headers": { "Authorization": "Bearer <your-jwt-access-token>" } } } }

校验行为（均出自文档）：

• Toolbox 会拦截连接、从authorizationServer拉取最新 JWKS，校验 JWT 的aud、签名和 scope 是否满足mcpEnabledauth service 的要求；
• 如果某个工具额外声明了工具级scopesRequired（见下），客户端令牌缺少所需 scope 时，服务端返回HTTP 403 Forbidden，并附带WWW-Authenticate挑战头指明缺失的 scope；
• 特别强调：Authorization头里的令牌必须是你配置的授权服务器签发的 JWT，不能是 Google Cloud Run 的 access token。

可选加固：工具级 scope

在工具配置里加scopesRequired，客户端令牌必须包含全部列出的 scope 才能调用该工具：

kind: tool name: update_flight_status type: postgres-sql source: my-pg-instance statement: | UPDATE flights SET status = $1 WHERE flight_number = $2 description: Update flight status authRequired: - my-generic-auth scopesRequired: - execute:sql - write:flights

已知限制与注意事项

• Cloud Run IAM 冲突：如果你的 Cloud Run 服务同时启用了 IAM 认证，需要用 Cloud Run 的 alternate auth header 传递 Cloud Run identity token，避免与 Toolbox 自身的鉴权互相冲突（文档指向 Cloud Run 的 service-to-service 认证说明）。
• PRM 一致性：手动 PRM 文件的resource必须与TOOLBOX_URL匹配；自动生成模式下resource即TOOLBOX_URL。
• 类型限制：mcpEnabled只对type: generic可用；scopesRequired、introspectionEndpoint、introspectionMethod、introspectionParamName等字段同样只在mcpEnabled为true时允许出现（见 generic.md 的 Reference 表）。
• 更多 PRM 手动挂载的实战细节（Secret 卷挂载、容器参数），可参考 Looker in Cloud Run 示例与 Claude Desktop with OAuth 示例，它们展示了--mcp-prm-file在真实客户端上的完整链路。
• 上线前建议同时阅读 CLI 参考中的 "Hardening Toolbox" 一节（--allowed-hosts、--allowed-origins、TLS 配置），本文不展开。

完成以上步骤后，验证路径是闭环的：/.well-known/oauth-protected-resource返回正确的resource与authorization_servers，携带合法 JWT 的客户端能连接/mcp，而缺少 scope 的调用会得到带WWW-Authenticate的 403 响应。

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox