如何为 MCP Toolbox 启用 MCP AuthorizationOAuth 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 MetadataPRM端点让客户端能自行发现授权服务器并发起授权流程。完成本文后你的 Toolbox 会拦截/mcp路由上的请求只有携带由你的 OIDC 授权服务器签发、aud与 scope 均合法的令牌的客户端才能进入而客户端能通过 PRM 端点自动拿到授权所需信息。前提与工作方式MCP Authorization 模式目前仅支持generic类型的 auth service见 Authentication 总览。启用后Toolbox 会从authorizationServer拉取 JWKSJSON 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 提供方基础 URLToolbox 会追加/.well-known/openid-configuration来发现 JWKSaudience令牌中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_URLhttp://127.0.0.1:5000 ./toolbox --tools-file tools.yaml或者显式使用--toolbox-url参数./toolbox --tools-file tools.yaml --toolbox-url http://127.0.0.1:5000Cloud Run 部署可选分支如果你要把服务发布到 Google Cloud Run用gcloud run deploy把目标 Cloud Run URL 通过--toolbox-url传入。注意该命令会实际部署/更新一个 Cloud Run 服务并绑定 Secret执行前确认项目、区域与镜像正确export IMAGEus-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.yamltools:latest \ --args--tools-file/app/tools.yaml,--address0.0.0.0,--port8080,--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.jsonCloud Run 场景需要先把文件上传到 Secret Manager 再挂载到部署中该命令会创建 Secret 并部署服务注意副作用gcloud secrets create prm_file --data-fileprm.json gcloud run deploy toolbox \ # ... previous args --set-secrets /app/tools.yamltools:latest,/app/prm.jsonprm_file:latest \ --args--tools-file/app/tools.yaml,--mcp-prm-file/app/prm.json,--port8080验证 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考