MCP Toolbox Core SDK

1.0.0 · active · verified Thu Apr 16

Python Base SDK for interacting with the Toolbox service, designed to seamlessly integrate the functionalities of the MCP Toolbox into your Gen AI applications by allowing you to load and use tools defined in the service as standard Python functions. It is actively maintained by Google and released version 1.0.0 on March 25, 2026, with related SDKs and the core Toolbox service undergoing rapid development and frequent updates.

Common errors

```
aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host 127.0.0.1:5000 ssl:False [Connection refused]
```
cause The Python client is unable to establish a connection with the MCP Toolbox server. This usually means the server is not running or is not accessible at the specified address and port.

fix Ensure the MCP Toolbox server application is actively running. Verify the `ToolboxClient` initialization URL (e.g., `http://127.0.0.1:5000`) matches the server's actual host and port. Check local firewall settings if connecting to a remote server.
```
toolbox_core.exceptions.ToolboxError: Tool 'non_existent_tool' not found on the server.
```
cause The client attempted to load a tool that is not defined or registered with the connected MCP Toolbox service. This can happen if the tool name is misspelled or the server's configuration does not expose that tool.

fix Confirm the exact name of the tool you are trying to load (e.g., 'get_weather') is correctly spelled and configured on your MCP Toolbox server. Review the server's tool definitions to ensure the tool is available.
```
TypeError: 'weather_tool' got an unexpected keyword argument 'city'
```
cause The parameters passed to an invoked tool do not match the expected signature defined by the tool on the MCP Toolbox server. This means the tool expected a different argument name or type.

fix Consult the documentation or schema for the specific tool you are invoking on the MCP Toolbox server. Ensure that the keyword arguments and their types passed in your Python code (e.g., `location="London"`) align perfectly with the tool's definition.

Warnings

breaking The underlying `mcp-toolbox` project, which `toolbox-core` integrates with, undergoes rapid development and frequently introduces breaking changes in its minor versions (e.g., 0.27.0, 0.29.0, 0.31.0, 0.32.0). Users should regularly monitor the `mcp-toolbox` changelog and be prepared to update their client code as tool definitions or APIs evolve.
Fix: Regularly check the main MCP Toolbox GitHub repository's CHANGELOG for updates and migration guides. Update `toolbox-core` and adapt client code as necessary.
gotcha The `ToolboxClient` requires a running and accessible MCP Toolbox server. Connection errors are common if the server is not started, is on a different address/port, or firewall rules prevent access.
Fix: Verify the MCP Toolbox server is running and its URL (`http://127.0.0.1:5000` by default in examples) is correctly configured in your client code or via the `TOOLBOX_SERVICE_URL` environment variable. Consult the MCP Toolbox Server Getting Started Guide for deployment instructions.
gotcha Tools loaded via `toolbox.load_tool()` must precisely match the names and expected parameters of tools defined on the connected MCP Toolbox service. Mismatches in name or parameter signature will lead to invocation failures.
Fix: Ensure the tool name passed to `load_tool()` (e.g., 'get_weather') exactly matches a tool configured on your running Toolbox server. Review the server's `tools.yaml` configuration or equivalent definition for correct tool names and parameter schemas.

Install

pip install toolbox-core Install stable version

Imports

ToolboxClient
```
from toolbox_core import ToolboxClient
```
The primary client for interacting with the MCP Toolbox service.

Quickstart

This quickstart demonstrates how to initialize the `ToolboxClient`, connect to a running MCP Toolbox service (requires a locally or remotely deployed server), and load and invoke a predefined tool, such as 'get_weather'. Make sure the `TOOLBOX_SERVICE_URL` environment variable is set or the default URL is correct.

import asyncio
import os
from toolbox_core import ToolboxClient

async def main():
    # Replace with the actual URL where your Toolbox service is running.
    # It's recommended to use an environment variable for the host in production.
    toolbox_host = os.environ.get("TOOLBOX_SERVICE_URL", "http://127.0.0.1:5000")
    print(f"Connecting to Toolbox service at: {toolbox_host}")

    try:
        async with ToolboxClient(toolbox_host) as toolbox:
            # Assuming 'get_weather' is a tool defined and exposed by your Toolbox service.
            # The tool name must match a tool configured on the running Toolbox server.
            weather_tool = await toolbox.load_tool("get_weather")
            print("Tool 'get_weather' loaded successfully.")

            # Invoke the loaded tool with its expected parameters.
            result = await weather_tool(location="London")
            print(f"Weather in London: {result}")
    except Exception as e:
        print(f"An error occurred: {e}")
        print("Ensure the MCP Toolbox server is running and accessible at the specified URL.")
        print("Refer to the MCP Toolbox Server Getting Started Guide for setup instructions (e.g., https://github.com/googleapis/mcp-toolbox).")

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →