googleapis/mcp-toolbox · error

MISSING_REQUIRED_CLIENT_CAPABILITY

MISSING_REQUIRED_CLIENT_CAPABILITY

Error message

missing required client capability: tool %q requires com.google.cloud/toolbox.v1 extension which is not supported by the client

What it means

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).

Source

Thrown at internal/server/mcp/v20260728/method.go:306

		attribute.String("gen_ai.operation.name", "execute_tool"),
	)

	// Verify tool belongs to the current group before resolving globally.
	if !g.ContainsTool(toolName) {
		err = fmt.Errorf("invalid tool name: tool with name %q does not exist", toolName)
		return jsonrpc.NewError(id, jsonrpc.INVALID_PARAMS, err.Error(), nil), err
	}

	tool, ok := primitiveMgr.GetTool(toolName)
	if !ok {
		err = fmt.Errorf("invalid tool name: tool with name %q does not exist", toolName)
		return jsonrpc.NewError(id, jsonrpc.INVALID_PARAMS, err.Error(), nil), err
	}

	supportedExts := ParseSupportedExtensions(req.Params.Meta.MetaClientCapabilities.Extensions)
	_, hasSecureParamsSupport := supportedExts["com.google.cloud/toolbox.v1"]
	if tool.HasSecureParams() && !hasSecureParamsSupport {
		err = fmt.Errorf("missing required client capability: tool %q requires com.google.cloud/toolbox.v1 extension which is not supported by the client", toolName)
		return jsonrpc.NewError(id, jsonrpc.MISSING_REQUIRED_CLIENT_CAPABILITY, err.Error(), nil), err
	}

	srcName := tool.GetSourceName()
	var src sources.Source
	if srcName != "" {
		src, ok = primitiveMgr.GetSource(srcName)
		if !ok {
			err = fmt.Errorf("unable to retrieve source for tool %s", toolName)
			return jsonrpc.NewError(id, jsonrpc.INTERNAL_ERROR, err.Error(), nil), err
		}
	}

	err = tool.ValidateSource(src)
	if err != nil {
		return jsonrpc.NewError(id, jsonrpc.INTERNAL_ERROR, err.Error(), nil), err
	}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Upgrade to an MCP client/SDK that supports and sends the com.google.cloud/toolbox.v1 extension in client capabilities.
2. Remove secure parameters from the tool config if your client cannot support them, replacing them with ordinary client-supplied parameters.
3. Use Google's official Gen AI Toolbox SDKs (e.g. langchain/google-genai toolbox integrations) which advertise the extension automatically.
4. Verify via tools/list that the target tool indeed has secure params, and route those calls through a capable client.

Example fix

// before
// plain client: no capabilities sent
{"method":"tools/call","params":{"name":"secure_query","arguments":{}}}
// after
// client sends toolbox extension capability
{"method":"tools/call","params":{"name":"secure_query","arguments":{},"_meta":{"capabilities":{"extensions":[{"name":"com.google.cloud/toolbox.v1"}]}}}}

// Before calling, check the tool needs the toolbox extension:
const tools = await client.listTools();
const tool = tools.tools.find(t => t.name === name);
const needsExt = tool && JSON.stringify(tool).includes('secure'); // or check declared secure params
const caps = client.getCapabilities?.() ?? {};
if (needsExt && !caps.extensions?.some(e => e.name === 'com.google.cloud/toolbox.v1')) {
  throw new Error(`client must advertise com.google.cloud/toolbox.v1 to call '${name}'`);
}

function clientSupportsToolboxExtension(clientCaps) {
  return Boolean(
    clientCaps &&
    clientCaps.extensions &&
    Array.isArray(clientCaps.extensions) &&
    clientCaps.extensions.some(e => e && e.name === 'com.google.cloud/toolbox.v1')
  );
}

try {
  const result = await client.callTool({ name, arguments: args });
} catch (e) {
  if (String(e.message).includes('missing required client capability')) {
    console.error(`Tool '${name}' needs the toolbox.v1 extension; switch to a capable SDK or remove secure params`);
    // fall back to a non-secure tool or an upgraded client
  }
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• INVALID_PARAMS
• INTERNAL_ERROR
• METHOD_NOT_FOUND
• INVALID_REQUEST
• INTERNAL_ERROR

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/be5258d29513527e. Report an issue: GitHub.