MCP Client

Toolbox SDKs vs Model Context Protocol (MCP)

Toolbox supports connections via the Model Context Protocol (MCP). However, Toolbox has several features which are not supported in the MCP specification (such as Authenticated Parameters and Authorized invocation).

We recommend using the native Toolbox Client SDKs over MCP clients to leverage these features. The Toolbox SDKs can be combined with MCP clients in many cases.

Protocol Versions

Toolbox currently supports the following versions of MCP specification:

• 2026-07-28
• 2025-11-25
• 2025-06-18
• 2025-03-26
• 2024-11-05

Secure Parameters and MCP Clients

Secure Parameters are supported on MCP protocol version 2026-07-28 or newer via the com.google.cloud/toolbox.v1 extension.

• Extension Negotiation: MCP clients declare support for this extension in params._meta["io.modelcontextprotocol/clientCapabilities"].extensions["com.google.cloud/toolbox.v1"].
• Manifests (tools/list): When negotiated, tools define application-controlled parameters under secureInputSchema alongside regular model parameters in inputSchema.
• Invocations (tools/call): Secure parameters are passed out-of-band in params.secureArguments, while model-generated arguments are passed in params.arguments.
• Fallback for Generic MCP Clients: Tools that require secure parameters are automatically filtered out from tools/list responses for clients that have not negotiated the com.google.cloud/toolbox.v1 extension (or clients using protocol versions prior to 2026-07-28). Attempting to call a secure tool directly without negotiated capability returns:
  • On protocol 2026-07-28: MissingRequiredClientCapabilityError (JSON-RPC code -32021).
  • On protocol versions prior to 2026-07-28: ToolNotFoundError / INVALID_PARAMS (JSON-RPC code -32602, “tool does not exist”), as secure tools are completely hidden from older protocols.
• Injection Defense: If a client or model attempts to pass a secure parameter inside standard arguments, the server rejects the parameter and returns a tool execution error (isError: true).

Toolbox AuthZ/AuthN Not Supported by MCP

The auth implementation in Toolbox is not supported in MCP’s auth specification. This includes:

• Authenticated Parameters
• Authorized Invocations

Connecting to Toolbox with an MCP client

Before you begin

1. Install Toolbox version 0.3.0+.

2. Make sure you’ve set up and initialized your database.

3. Set up your tools.yaml file.

Connecting via Standard Input/Output (stdio)

Toolbox supports the stdio transport protocol. Users that wish to use stdio will have to include the --stdio flag when running Toolbox.

./toolbox --stdio

When running with stdio, Toolbox will listen via stdio instead of acting as a remote HTTP server. Logs will be set to the warn level by default. debug and info logs are not supported with stdio.

Connecting via HTTP

Toolbox supports the HTTP transport protocol with and without SSE.

• HTTP with SSE (deprecated)
• Streamable HTTP

{
  "mcpServers": {
    "toolbox": {
      "type": "sse",
      "url": "http://127.0.0.1:5000/mcp/sse",
    }
  }
}

{
  "mcpServers": {
    "toolbox": {
      "type": "http",
      "url": "http://127.0.0.1:5000/mcp",
    }
  }
}

Using the MCP Inspector with Toolbox

Use MCP Inspector for testing and debugging Toolbox server.

• STDIO
• HTTP with SSE (deprecated)
• Streamable HTTP

Tested Clients