genai-toolbox/docs/en/sdks/python-sdk/adk/index.md

title, type, weight, description

title	type	weight	description
ADK	docs	8	MCP Toolbox SDK for integrating functionalities of MCP Toolbox into your ADK apps.

Overview

The toolbox-adk package provides a Python interface to the MCP Toolbox service, enabling you to load and invoke tools from your own applications.

Installation

pip install google-adk[toolbox]

Usage

The primary entry point is the ToolboxToolset, which loads tools from a remote Toolbox server and adapts them for use with ADK agents.

{{< notice note>}} This package contains the core implementation of the ToolboxToolset. The ToolboxToolset provided in the google-adk package is a shim that simply delegates all functionality to this implementation. {{< /notice >}}

from google.adk.tools.toolbox_toolset import ToolboxToolset
from google.adk.agents import Agent

# Create the Toolset
toolset = ToolboxToolset(
    server_url="http://127.0.0.1:5000" 
)

# Use in your ADK Agent
agent = Agent(tools=[toolset])

Transport Protocols

The SDK supports multiple transport protocols for communicating with the Toolbox server. By default, the client uses the latest supported version of the Model Context Protocol (MCP).

You can explicitly select a protocol using the protocol option during toolset initialization. This is useful if you need to use the native Toolbox HTTP protocol or pin the client to a specific legacy version of MCP.

{{< notice note>}}

• Native Toolbox Transport: This uses the service's native REST over HTTP API.
• MCP Transports: These options use the Model Context Protocol over HTTP. {{< /notice >}}

Supported Protocols

Constant	Description
Protocol.MCP	(Default) Alias for the default MCP version (currently 2025-06-18).
Protocol.TOOLBOX	The native Toolbox HTTP protocol.
Protocol.MCP_v20251125	MCP Protocol version 2025-11-25.
Protocol.MCP_v20250618	MCP Protocol version 2025-06-18.
Protocol.MCP_v20250326	MCP Protocol version 2025-03-26.
Protocol.MCP_v20241105	MCP Protocol version 2024-11-05.

Example

If you wish to use the native Toolbox protocol:

from toolbox_adk import ToolboxToolset
from toolbox_core.protocol import Protocol

toolset = ToolboxToolset(
    server_url="http://127.0.0.1:5000",
    protocol=Protocol.TOOLBOX
)

If you want to pin the MCP Version 2025-03-26:

from toolbox_adk import ToolboxToolset
from toolbox_core.protocol import Protocol

toolset = ToolboxToolset(
    server_url="http://127.0.0.1:5000",
    protocol=Protocol.MCP_v20250326
)

{{< notice tip>}} By default, it uses Toolbox Identity (no authentication), which is suitable for local development.

For production environments (Cloud Run, GKE) or accessing protected resources, see the Authentication section for strategies like Workload Identity or OAuth2. {{< /notice >}}

Authentication

The ToolboxToolset requires credentials to authenticate with the Toolbox server. You can configure these credentials using the CredentialStrategy factory methods.

The strategies handle two main types of authentication:

• Client-to-Server: Securing the connection to the Toolbox server (e.g., Workload Identity, API keys).
• User Identity: Authenticating the end-user for specific tools (e.g., 3-legged OAuth).

1. Workload Identity (ADC)

Recommended for Cloud Run, GKE, or local development with gcloud auth login.

Uses the agent's Application Default Credentials (ADC) to generate an OIDC token. This is the standard way for one service to authenticate to another on Google Cloud.

from toolbox_adk import CredentialStrategy, ToolboxToolset

# target_audience: The URL of your Toolbox server
creds = CredentialStrategy.workload_identity(target_audience="https://my-toolbox-service.run.app")

toolset = ToolboxToolset(
    server_url="https://my-toolbox-service.run.app",
    credentials=creds
)

2. User Identity (OAuth2)

Recommended for tools that act on behalf of the user.

Configures the ADK-native interactive 3-legged OAuth flow to get consent and credentials from the end-user at runtime. This strategy is passed to the ToolboxToolset just like any other credential strategy.

from toolbox_adk import CredentialStrategy, ToolboxToolset

creds = CredentialStrategy.user_identity(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)

# The toolset will now initiate OAuth flows when required by tools
toolset = ToolboxToolset(
    server_url="...",
    credentials=creds
)

3. API Key

Use a static API key passed in a specific header (default: X-API-Key).

from toolbox_adk import CredentialStrategy

# Default header: X-API-Key
creds = CredentialStrategy.api_key(key="my-secret-key")

# Custom header
creds = CredentialStrategy.api_key(key="my-secret-key", header_name="X-My-Header")

4. HTTP Bearer Token

Manually supply a static bearer token.

from toolbox_adk import CredentialStrategy

creds = CredentialStrategy.manual_token(token="your-static-bearer-token")

5. Manual Google Credentials

Use an existing google.auth.credentials.Credentials object.

from toolbox_adk import CredentialStrategy
import google.auth

creds_obj, _ = google.auth.default()
creds = CredentialStrategy.manual_credentials(credentials=creds_obj)

6. Toolbox Identity (No Auth)

Use this if your Toolbox server does not require authentication (e.g., local development).

from toolbox_adk import CredentialStrategy

creds = CredentialStrategy.toolbox_identity()

7. Native ADK Integration

Convert ADK-native AuthConfig or AuthCredential objects.

from toolbox_adk import CredentialStrategy

# From AuthConfig
creds = CredentialStrategy.from_adk_auth_config(auth_config)

# From AuthCredential + AuthScheme
creds = CredentialStrategy.from_adk_credentials(auth_credential, scheme)

8. Tool-Specific Authentication

Resolve authentication tokens dynamically for specific tools.

Some tools may define their own authentication requirements (e.g., Salesforce OAuth, GitHub PAT) via authSources in their schema. You can provide a mapping of getters to resolve these tokens at runtime.

async def get_salesforce_token():
    # Fetch token from secret manager or reliable source
    return "sf-access-token"

toolset = ToolboxToolset(
    server_url="...",
    auth_token_getters={
        "salesforce-auth": get_salesforce_token,   # Async callable
        "github-pat": lambda: "my-pat-token"       # Sync callable or static lambda
    }
)

Advanced Configuration

Additional Headers

You can inject custom headers into every request made to the Toolbox server. This is useful for passing tracing IDs, API keys, or other metadata.

toolset = ToolboxToolset(
    server_url="...",
    additional_headers={
        "X-Trace-ID": "12345",
        "X-My-Header": lambda: get_dynamic_header_value() # Can be a callable
    }
)

Global Parameter Binding

Bind values to tool parameters globally across all loaded tools. These values will be fixed and hidden from the LLM.

• Schema Hiding: The bound parameters are removed from the tool schema sent to the model, simplifying the context window.
• Auto-Injection: The values are automatically injected into the tool arguments during execution.

toolset = ToolboxToolset(
    server_url="...",
    bound_params={
        # 'region' will be removed from the LLM schema and injected automatically
        "region": "us-central1",
        "api_key": lambda: get_api_key() # Can be a callable
    }
)