如何配置 MCP Toolbox 的 Secure Parameters 让应用端敏感参数带外传递给工具【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox在 MCP Toolbox 中如果某个工具需要端到端的敏感运行时上下文——例如终端用户的customer_id、租户标识或 session token——把这些值交给 LLM 填写或查看会带来两个风险提示词注入可能篡改customer_id去访问其他租户数据敏感标识符还会以明文进入第三方 LLM 的上下文窗口和补全日志。Secure Parameters 就是为此设计的把这类参数从工具的标准inputSchema/arguments中剥离出来放入独立的secureInputSchema/secureArguments由宿主应用在代码里绑定、随tools/call请求带外传给服务器LLM 全程看不到也碰不到这些参数。完成本文后你会得到一个这样的链路Toolbox 服务端把敏感参数标记为secure: true应用端 SDK 绑定真实值调用时敏感值走secureArguments字段传输同时验证模型无法通过标准arguments覆盖这些值。适用前提Toolbox 服务已能启动并加载你的工具配置默认监听127.0.0.1:5000见 CLI 参考。MCP 协议版本为2026-07-28且服务器侧启用com.google.cloud/toolbox.v1扩展默认广播见下文确认方式。客户端使用官方 SDK 时Python 的toolbox-core需要1.4.0及以上版本pip install toolbox-core安装最新版SDK 默认的Protocol.MCP当前即指向2026-07-28。Secure parameters 适用于客户端提供的运行时值如customer_id、终端用户上下文。数据库凭据服务账号密码、API key 等应直接配置在 Data Source 配置里而不是作为按请求传递的工具参数。第一步在工具定义里标记 secure 参数在tools.yaml中把需要带外传递的参数加secure: true字段kind: tool name: search_secure_data type: postgres-sql source: my-pg-instance statement: | SELECT * FROM sessions WHERE customer_id $1 AND session_token $2 parameters: - name: customer_id type: string description: Sensitive customer identifier supplied out-of-band by the calling application secure: true - name: session_token type: string description: Sensitive session token supplied out-of-band by the calling application secure: truesecure字段的配置约束来自 Tools 配置文档Secure 参数始终为必填不能设为可选。同一参数不能同时出现secure: true和default、authServices或required: false。要求协议版本2026-07-28与com.google.cloud/toolbox.v1扩展。第二步启动服务并确认扩展未被禁用用--config指定工具配置文件启动服务器./toolbox --config tools.yamlcom.google.cloud/toolbox.v1扩展默认广播。如果你用--disable-ext禁用过它--disable-ext com.google.cloud/toolbox.v1该扩展会从服务器广播的能力中移除支持该扩展的客户端将看不到带 secure 参数的工具——所以做 Secure Parameters 时不要禁用这个扩展。确认方式客户端在server/discover阶段查看capabilities.extensions返回中应包含com.google.cloud/toolbox.v1: {}见 扩展规范 中的文档示例。tools/list的行为取决于客户端是否声明了该扩展支持扩展的客户端定义了 secure 参数的工具正常出现在tools数组中非敏感参数在inputSchema敏感参数被分离到secureInputSchema两个 schema 都看不到通过 URL 参数绑定的参数。不支持扩展的客户端或协议版本早于2026-07-28的旧客户端定义了 secure 参数的工具直接从工具列表中过滤掉防止其被调用。第三步在应用端绑定 secure 参数以 Pythontoolbox-coreSDK 为例其他语言 SDK 的等价方法见后文。SDK 会自动完成协议协商与扩展能力声明并负责把绑定值放进secureArguments。方式 A加载工具后再绑定。每个绑定方法返回一个新的不可变工具实例原实例不变from toolbox_core import ToolboxClient async with ToolboxClient(http://127.0.0.1:5000) as toolbox: tool await toolbox.load_tool(search_secure_data) # 绑定单个 secure 参数 bound_tool tool.bind_secure_param(customer_id, cust_12345) # 或一次绑定多个 secure 参数 multi_bound_tool tool.bind_secure_params({ customer_id: cust_12345, session_token: token-xyz, })方式 B加载时直接绑定。SDK 会校验你提供的 key 确实存在于目标工具的 secure 参数上async with ToolboxClient(http://127.0.0.1:5000) as toolbox: tool await toolbox.load_tool( search_secure_data, secure_params{customer_id: cust_12345} ) # 也可以对整个 toolset 绑定 tools await toolbox.load_toolset( my-toolset, secure_params{customer_id: cust_12345} )动态值把参数绑定到同步或异步可调用对象每次工具被调用时才求值适合按请求变化的值async def get_current_user_token() - str: # 动态获取当前会话的 token return session-token-abc secure_tool tool.bind_secure_param(auth_token, get_current_user_token)调用时只传标准参数已绑定的 secure 值会自动附加result await multi_bound_tool(session_tokentoken-xyz)防混用的快速失败SDK 对绑定方法做互斥校验绑定错了会在本地立即报ValueError而不是发到服务端用bind_param()/bind_params()绑 secure 参数ValueError: parameter name is a secure parameter; use bind_secure_param/bind_secure_params instead用bind_secure_param()/bind_secure_params()绑普通参数ValueError: parameter name is a regular parameter; use bind_param/bind_params instead同步代码可用ToolboxSyncClient用法相同with代替async with无awaitfrom toolbox_core import ToolboxSyncClient with ToolboxSyncClient(http://127.0.0.1:5000) as toolbox: tool toolbox.load_tool( search_secure_data, secure_params{customer_id: cust_12345} ) result tool()JavaScript/TypeScript 与 Go SDK 提供等价能力方法名分别为bindSecureParam/bindSecureParamsloadTool第四参数传 secureParams和core.WithBindSecureParamString/core.WithBindSecureParamStringFuncToolFrom或NewToolboxClient的WithDefaultToolOptions中设置完整示例见 Tools 配置文档的 SDK Usage Examples 一节和 Python Core SDK 文档。验证带外传递是否生效1. 检查工具清单的 schema 分离。用支持扩展的客户端执行tools/list带 secure 参数的工具应同时携带inputSchema只含非敏感参数和secureInputSchema只含敏感参数。以下 JSON 为规范文档中的文档示例{ name: search_customer_records, description: Searches customer records by query filter., inputSchema: { type: object, properties: { query: { type: string, description: The search query string. } }, required: [query] }, secureInputSchema: { type: object, properties: { customer_id: { type: string, description: Sensitive customer identifier supplied out-of-band by the calling application. } }, required: [customer_id] } }SDK 加载工具后也可以从本地验证隔离效果secure 参数会从公开的工具声明、docstring 和运行时函数签名__signature__/inspect.signature(tool)中完全移除。2. 检查请求报文。绑定值通过tools/call请求的secureArguments字段传输与模型给出的arguments隔离。以下报文为规范文档中的文档示例应用原始 MCP 客户端时需自行在_meta中声明扩展能力与2026-07-28协议版本使用官方 SDK 时这一步由 SDK 完成{ jsonrpc: 2.0, id: call-1, method: tools/call, params: { name: search_customer_records, arguments: { query: recent transactions }, secureArguments: { customer_id: cust_12345 }, _meta: { io.modelcontextprotocol/protocolVersion: 2026-07-28, io.modelcontextprotocol/clientInfo: { name: MyApplicationClient, version: 1.0.0 }, io.modelcontextprotocol/clientCapabilities: { extensions: { com.google.cloud/toolbox.v1: {} } } } } }3. 验证模型无法覆盖敏感值。完整错误判定表见 Secure Parameters 规范核心条目错误类型级别 / 返回错误码条件缺少客户端扩展能力JSON-RPC 错误-32021MISSING_REQUIRED_CLIENT_CAPABILITY在2026-07-28协议上调用带 secure 参数的工具但客户端未在能力中声明com.google.cloud/toolbox.v1旧协议调用 secure 工具JSON-RPC 错误-32602INVALID_PARAMS在早于2026-07-28的协议版本上调用 secure 工具工具已被隐藏返回invalid tool name: tool with name name does not existsecure 参数出现在argumentsJSON-RPC 错误-32602INVALID_PARAMS带secure: true的参数被放进标准arguments非 secure 参数出现在secureArgumentsJSON-RPC 错误-32602INVALID_PARAMS普通参数被放进secureArguments覆盖了 URL 绑定的参数工具执行错误IsError: trueN/A该参数已通过 URL 查询参数绑定客户端又试图传值缺少必填 secure 参数工具执行错误IsError: trueN/A必填的 secure 参数既没在secureArguments提供、也没有 URL 绑定另外SDK 侧还有前置的快速失败发出网络请求前SDK 会在本地校验所有必填 secure 参数是否已绑定缺失时直接抛客户端错误请求根本不会上线。限制与边界Secure 参数与authServicesAuthenticated Parameters是两套机制后者从客户端 ID token 的声明字段自动填充前者由宿主应用代码绑定。同一个参数不能同时使用两者。通过 URL 查询参数绑定的参数会从inputSchema和secureInputSchema中同时省略由服务器自动填充此时客户端再传同名参数会报parameter param_name is bound by URL and cannot be provided in client arguments。不支持com.google.cloud/toolbox.v1扩展的客户端不会报错而是看不到这些工具工具列表中被过滤这是 fail-closed 设计的一部分。该功能属于实验性 MCP 扩展extensions/目录下的 扩展 README 说明其版本策略若未来该能力被纳入 MCP 官方规范会从实验扩展包中移除客户端需要切换到官方实现。继续深入Secure Parameters 完整规范含发现、协商、执行与错误矩阵类型定义ToolWithSecureParams与CallToolRequestParamsWithSecureParams接口Tools 配置文档中 Secure Parameters 一节与三种语言的 SDK 绑定示例各 SDK 的框架集成指南PythonCore/ADK/LangChain/LlamaIndex、JavaScript/TypeScriptCore/ADK、GoCore/tbadk/Genkit入口在 Toolbox SDKs【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考