{"record":{"id":"be5258d29513527e","repo":"googleapis/mcp-toolbox","slug":"missing-required-client-capability","errorCode":"MISSING_REQUIRED_CLIENT_CAPABILITY","errorMessage":"missing required client capability: tool %q requires com.google.cloud/toolbox.v1 extension which is not supported by the client","messagePattern":"missing required client capability: tool %q requires com\\.google\\.cloud/toolbox\\.v1 extension which is not supported by the client","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/server/mcp/v20260728/method.go","lineNumber":306,"sourceCode":"\t\tattribute.String(\"gen_ai.operation.name\", \"execute_tool\"),\n\t)\n\n\t// Verify tool belongs to the current group before resolving globally.\n\tif !g.ContainsTool(toolName) {\n\t\terr = fmt.Errorf(\"invalid tool name: tool with name %q does not exist\", toolName)\n\t\treturn jsonrpc.NewError(id, jsonrpc.INVALID_PARAMS, err.Error(), nil), err\n\t}\n\n\ttool, ok := primitiveMgr.GetTool(toolName)\n\tif !ok {\n\t\terr = fmt.Errorf(\"invalid tool name: tool with name %q does not exist\", toolName)\n\t\treturn jsonrpc.NewError(id, jsonrpc.INVALID_PARAMS, err.Error(), nil), err\n\t}\n\n\tsupportedExts := ParseSupportedExtensions(req.Params.Meta.MetaClientCapabilities.Extensions)\n\t_, hasSecureParamsSupport := supportedExts[\"com.google.cloud/toolbox.v1\"]\n\tif tool.HasSecureParams() && !hasSecureParamsSupport {\n\t\terr = fmt.Errorf(\"missing required client capability: tool %q requires com.google.cloud/toolbox.v1 extension which is not supported by the client\", toolName)\n\t\treturn jsonrpc.NewError(id, jsonrpc.MISSING_REQUIRED_CLIENT_CAPABILITY, err.Error(), nil), err\n\t}\n\n\tsrcName := tool.GetSourceName()\n\tvar src sources.Source\n\tif srcName != \"\" {\n\t\tsrc, ok = primitiveMgr.GetSource(srcName)\n\t\tif !ok {\n\t\t\terr = fmt.Errorf(\"unable to retrieve source for tool %s\", toolName)\n\t\t\treturn jsonrpc.NewError(id, jsonrpc.INTERNAL_ERROR, err.Error(), nil), err\n\t\t}\n\t}\n\n\terr = tool.ValidateSource(src)\n\tif err != nil {\n\t\treturn jsonrpc.NewError(id, jsonrpc.INTERNAL_ERROR, err.Error(), nil), err\n\t}\n","sourceCodeStart":288,"sourceCodeEnd":324,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/server/mcp/v20260728/method.go#L288-L324","documentation":"Some tools declare secure parameters whose values are injected server-side and must not travel through the client. Such tools require the client to advertise the `com.google.cloud/toolbox.v1` extension capability in the request's _meta client capabilities. If a tool with secure params is called without that capability declared, the handler returns MISSING_REQUIRED_CLIENT_CAPABILITY (internal/server/mcp/v20260728/method.go:306).","triggerScenarios":"tools/call on a tool whose definition includes secure parameters, when req.Params.Meta.MetaClientCapabilities.Extensions lacks the `com.google.cloud/toolbox.v1` entry (i.e. ParseSupportedExtensions finds no support).","commonSituations":"Using a generic MCP client that doesn't send Toolbox client-capability extensions against a toolbox config that uses secure params (e.g. authenticated/user-bound parameters); older client SDK predating the secure-params extension.","solutions":["Upgrade to an MCP client/SDK that supports and sends the com.google.cloud/toolbox.v1 extension in client capabilities.","Remove secure parameters from the tool config if your client cannot support them, replacing them with ordinary client-supplied parameters.","Use Google's official Gen AI Toolbox SDKs (e.g. langchain/google-genai toolbox integrations) which advertise the extension automatically.","Verify via tools/list that the target tool indeed has secure params, and route those calls through a capable client."],"exampleFix":"// before\n// plain client: no capabilities sent\n{\"method\":\"tools/call\",\"params\":{\"name\":\"secure_query\",\"arguments\":{}}}\n// after\n// client sends toolbox extension capability\n{\"method\":\"tools/call\",\"params\":{\"name\":\"secure_query\",\"arguments\":{},\"_meta\":{\"capabilities\":{\"extensions\":[{\"name\":\"com.google.cloud/toolbox.v1\"}]}}}}","handlingStrategy":"type-guard","validationCode":"// Before calling, check the tool needs the toolbox extension:\nconst tools = await client.listTools();\nconst tool = tools.tools.find(t => t.name === name);\nconst needsExt = tool && JSON.stringify(tool).includes('secure'); // or check declared secure params\nconst caps = client.getCapabilities?.() ?? {};\nif (needsExt && !caps.extensions?.some(e => e.name === 'com.google.cloud/toolbox.v1')) {\n  throw new Error(`client must advertise com.google.cloud/toolbox.v1 to call '${name}'`);\n}","typeGuard":"function clientSupportsToolboxExtension(clientCaps) {\n  return Boolean(\n    clientCaps &&\n    clientCaps.extensions &&\n    Array.isArray(clientCaps.extensions) &&\n    clientCaps.extensions.some(e => e && e.name === 'com.google.cloud/toolbox.v1')\n  );\n}","tryCatchPattern":"try {\n  const result = await client.callTool({ name, arguments: args });\n} catch (e) {\n  if (String(e.message).includes('missing required client capability')) {\n    console.error(`Tool '${name}' needs the toolbox.v1 extension; switch to a capable SDK or remove secure params`);\n    // fall back to a non-secure tool or an upgraded client\n  }\n}","preventionTips":["Use Google's official Gen AI Toolbox SDKs which send the com.google.cloud/toolbox.v1 capability automatically.","Audit toolbox configs for secure params and match them with capable clients.","On capability errors, either upgrade the client or remove secure params from the tool.","Test secure-param tools end-to-end with the production client SDK before rollout."],"tags":["mcp","client-capabilities","secure-params","tools-call","go"],"backgroundTag":"missing-client-capability","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}