Skip to content

docs: cleanup README #581

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AnmolShukla2002 wants to merge 9 commits into
base: main
Choose a base branch
from
Open

docs: cleanup README #581

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
116a47e
docs: cleanup README
AnmolShukla2002 Mar 10, 2026
e5dfcce
adk readme cleanup v1
AnmolShukla2002 Mar 12, 2026
d5610a4
adk readme cleanup v2
AnmolShukla2002 Mar 12, 2026
ee236d9
core readme cleanup v1
AnmolShukla2002 Mar 12, 2026
da04ed7
core readme cleanup v2
AnmolShukla2002 Mar 12, 2026
52d2257
langchain readme cleanup v1
AnmolShukla2002 Mar 12, 2026
bc0964b
langchain readme cleanup v2
AnmolShukla2002 Mar 12, 2026
dfb132f
langchain readme cleanup v3
AnmolShukla2002 Mar 12, 2026
6f01554
llamaindex readme cleanup v1
AnmolShukla2002 Mar 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 13 additions & 75 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,83 +14,33 @@ applications. These SDKs allow you to load tools defined in Toolbox and use them
as standard Python functions or objects within popular orchestration frameworks
or your custom code.

This simplifies the process of incorporating external functionalities (like
Databases or APIs) managed by Toolbox into your GenAI applications.
For comprehensive guides and advanced configuration, visit the [Main Documentation Site](https://googleapis.github.io/genai-toolbox/).


<!-- TOC -->
- [Overview](#overview)
- [Which Package Should I Use?](#which-package-should-i-use)
- [Available Packages](#available-packages)
- [Getting Started](#getting-started)
- [Quick Start](#quick-start)
Copy link
Contributor

@anubhav756 anubhav756 Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: We generally have Quickstart as a single word.

- [Contributing](#contributing)
- [License](#license)
- [Support](#support)

<!-- /TOC -->

## Overview

The MCP Toolbox service provides a centralized way to manage and expose tools
(like API connectors, database query tools, etc.) for use by GenAI applications.

These Python SDKs act as clients for that service. They handle the communication needed to:

* Fetch tool definitions from your running Toolbox instance.
* Provide convenient Python objects or functions representing those tools.
* Invoke the tools (calling the underlying APIs/services configured in Toolbox).
* Handle authentication and parameter binding as needed.

By using these SDKs, you can easily leverage your Toolbox-managed tools directly
within your Python applications or AI orchestration frameworks.

## Which Package Should I Use?

Choosing the right package depends on how you are building your application:

* [`toolbox-adk`](https://github.com/googleapis/mcp-toolbox-sdk-python/tree/main/packages/toolbox-adk):
Use this package if you are building your application using Google ADK (Agent Development Kit).
It provides tools that are directly compatible with the
Google ADK ecosystem (`BaseTool` / `BaseToolset` interface) handling authentication propagation, header management, and tool wrapping automatically.
* [`toolbox-core`](https://github.com/googleapis/mcp-toolbox-sdk-python/tree/main/packages/toolbox-core):
Use this package if you are not using LangChain/LangGraph or any other
orchestration framework, or if you need a framework-agnostic way to interact
with Toolbox tools (e.g., for custom orchestration logic or direct use in
Python scripts).
* [`toolbox-langchain`](https://github.com/googleapis/mcp-toolbox-sdk-python/tree/main/packages/toolbox-langchain):
Use this package if you are building your application using the LangChain or
LangGraph frameworks. It provides tools that are directly compatible with the
LangChain ecosystem (`BaseTool` interface), simplifying integration.
* [`toolbox-llamaindex`](https://github.com/googleapis/mcp-toolbox-sdk-python/tree/main/packages/toolbox-llamaindex):
Use this package if you are building your application using the LlamaIndex framework.
It provides tools that are directly compatible with the
LlamaIndex ecosystem (`BaseTool` interface), simplifying integration.

## Available Packages

This repository hosts the following Python packages. See the package-specific
README for detailed installation and usage instructions:
This repository hosts the following Python packages. See the package-specific READMEs or the docsite for detailed usage:

| Package | Target Use Case | Integration | Path | Details (README) | PyPI Status |
| :------ | :---------- | :---------- | :---------------------- | :---------- | :---------
| `toolbox-adk` | Google ADK applications | Google ADK | `packages/toolbox-adk/` | 📄 [View README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-adk/README.md) | ![pypi version](https://img.shields.io/pypi/v/toolbox-adk.svg) |
| `toolbox-core` | Framework-agnostic / Custom applications | Use directly / Custom | `packages/toolbox-core/` | 📄 [View README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-core/README.md) | ![pypi version](https://img.shields.io/pypi/v/toolbox-core.svg) |
| `toolbox-langchain` | LangChain / LangGraph applications | LangChain / LangGraph | `packages/toolbox-langchain/` | 📄 [View README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-langchain/README.md) | ![pypi version](https://img.shields.io/pypi/v/toolbox-langchain.svg) |
| `toolbox-llamaindex` | LlamaIndex applications | LlamaIndex | `packages/toolbox-llamaindex/` | 📄 [View README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-llamaindex/README.md) | ![pypi version](https://img.shields.io/pypi/v/toolbox-llamaindex.svg) |
| Package | Target Use Case | Path | Documentation |
| :------ | :---------- | :--- | :---------- |
| `toolbox-core` | Framework-agnostic / Custom apps | `packages/toolbox-core/` | [Python Core Guide](https://googleapis.github.io/genai-toolbox/sdks/python-sdk/core/) |
| `toolbox-adk` | Google ADK Integration | `packages/toolbox-adk/` | [ADK Package Guide](https://googleapis.github.io/genai-toolbox/sdks/python-sdk/adk/) |
| `toolbox-langchain` | LangChain / LangGraph Integration | `packages/toolbox-langchain/` | [LangChain Guide](https://googleapis.github.io/genai-toolbox/sdks/python-sdk/langchain/) |
| `toolbox-llamaindex` | LlamaIndex Integration | `packages/toolbox-llamaindex/` | [LlamaIndex Guide](https://googleapis.github.io/genai-toolbox/sdks/python-sdk/llamaindex/) |

## Quick Start
Copy link
Contributor

@anubhav756 anubhav756 Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Quickstart as a single word?


## Getting Started

To get started using Toolbox tools with an application, follow these general steps:

1. **Set up and Run the Toolbox Service:**

Before using the SDKs, you need the main MCP Toolbox service running. Follow
the instructions here: [**Toolbox Getting Started
Guide**](https://github.com/googleapis/genai-toolbox?tab=readme-ov-file#getting-started)

1. **Set up the Toolbox Service**: Ensure you have a running MCP Toolbox server. Follow the [Toolbox Server Getting Started Guide](https://github.com/googleapis/genai-toolbox?tab=readme-ov-file#getting-started).
2. **Install the Appropriate SDK:**

Choose the package based on your needs (see "[Which Package Should I Use?](#which-package-should-i-use)" above) and install it:

```bash
# For the Google ADK
Expand All @@ -109,19 +59,7 @@ To get started using Toolbox tools with an application, follow these general ste
# For the LlamaIndex integration
pip install toolbox-llamaindex
```

3. **Use the SDK:**

Consult the README for your chosen package (linked in the "[Available
Packages](#available-packages)" section above) for detailed instructions on
how to connect the client, load tool definitions, invoke tools, configure
authentication/binding, and integrate them into your application or
framework.

> [!TIP]
> For a complete, end-to-end example including setting up the service and using
> an SDK, see the full tutorial: [**Toolbox Quickstart
> Tutorial**](https://googleapis.github.io/genai-toolbox/getting-started/local_quickstart)
3. **Explore Tutorials**: Check out the [Python Quickstart Tutorial](https://googleapis.github.io/genai-toolbox/getting-started/local_quickstart/) for a full walkthrough.

## Contributing

Expand Down
243 changes: 5 additions & 238 deletions packages/toolbox-adk/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,12 @@

This package allows Google ADK (Agent Development Kit) agents to natively use tools from the [MCP Toolbox](https://github.com/googleapis/genai-toolbox).

It provides a seamless bridge between the `toolbox-core` SDK and the ADK's `BaseTool` / `BaseToolset` interfaces, handling authentication propagation, header management, and tool wrapping automatically.
For detailed guides, authentication examples, and advanced configuration, visit the [Python SDK ADK Guide](https://googleapis.github.io/genai-toolbox/sdks/python-sdk/adk/).

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
- [Transport Protocols](#transport-protocols)
- [Supported Protocols](#supported-protocols)
- [Example](#example)
- [Authentication](#authentication)
- [Workload Identity (ADC)](#1-workload-identity-adc)
- [User Identity (OAuth2)](#2-user-identity-oauth2)
- [API Key](#3-api-key)
- [HTTP Bearer Token](#4-http-bearer-token)
- [Manual Google Credentials](#5-manual-google-credentials)
- [Toolbox Identity (No Auth)](#6-toolbox-identity-no-auth)
- [Native ADK Integration](#7-native-adk-integration)
- [Tool-Specific Authentication](#8-tool-specific-authentication)
- [Advanced Configuration](#advanced-configuration)
- [Additional Headers](#additional-headers)
- [Global Parameter Binding](#global-parameter-binding)

## Installation

Expand All @@ -34,229 +19,11 @@ pip install toolbox-adk

## Usage

The primary entry point is the `ToolboxToolset`, which loads tools from a remote Toolbox server and adapts them for use with ADK agents.
The toolbox-adk package provides a seamless bridge to natively use MCP Toolbox tools within ADK agents. For detailed guides and advanced configuration, please visit the following sections on our [Documentation Site](https://googleapis.github.io/genai-toolbox/sdks/python-sdk/adk/):
Copy link
Contributor

@anubhav756 anubhav756 Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The toolbox-adk package provides a seamless bridge to natively use MCP Toolbox tools within ADK agents. For detailed guides and advanced configuration, please visit the following sections on our [Documentation Site](https://googleapis.github.io/genai-toolbox/sdks/python-sdk/adk/):
The `toolbox-adk` package provides a seamless bridge to natively use MCP Toolbox tools within ADK agents. For detailed guides and advanced configuration, please visit the following sections on our [Documentation Site](https://googleapis.github.io/genai-toolbox/sdks/python-sdk/adk/):


> [!NOTE]
> The `ToolboxToolset` in this package mirrors the `ToolboxToolset` in the [`adk-python`](https://github.com/google/adk-python) package. The `adk-python` version is a shim that delegates all functionality to this implementation.

```python
from toolbox_adk import ToolboxToolset
from google.adk 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.

> [!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**.

### Supported Protocols

| Constant | Description |
| :--- | :--- |
| `Protocol.MCP` | **(Default)** Alias for the default MCP version (currently `2025-06-18`). |
| `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. |

> [!WARNING]

### Example


```python
from toolbox_adk import ToolboxToolset
from toolbox_core.protocol import Protocol

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

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

```python
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
)
```

> [!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](#authentication) section for strategies like Workload Identity or OAuth2.

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

```python
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.

```python
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`).*

```python
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.*

```python
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.*

```python
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).*

```python
from toolbox_adk import CredentialStrategy

creds = CredentialStrategy.toolbox_identity()
```

### 7. Native ADK Integration
*Convert ADK-native `AuthConfig` or `AuthCredential` objects.*

```python
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.

```python
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.

```python
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.

```python
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
}
)
```
- [Transport Protocols](https://googleapis.github.io/genai-toolbox/sdks/python-sdk/adk/#transport-protocols)
Copy link
Contributor

@anubhav756 anubhav756 Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see the transport section still has the deprecated TOOLBOX protocol. Can we ensure syncing all the READMEs', across languages and orchestrations, latest contents to the docsite?

- [Authentication](https://googleapis.github.io/genai-toolbox/sdks/python-sdk/adk/#authentication)
- [Advanced Configuration](https://googleapis.github.io/genai-toolbox/sdks/python-sdk/adk/#advanced-configuration)

## Contributing

Expand Down
Loading
Loading