Registry / gcp / toolbox-core

toolbox-core

JSON →
library1.1.0pypypi✓ verified 86d ago

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.

pip install toolbox-core
INSTALL
IMPORT
SIG · TOOLBOX-CORE
T
toolbox-core
gcppythonv1.1.0
Install
8.0s avg
Import
1071ms
Disk
62MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 1.125s · 61.7MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 8.0s · import 1.017s · 63MB
62MB installed
● package 62MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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())
Debug
Known issues
breakingThe 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.
affects: <1.0.0 (and future minor versions of the core service)
gotchaThe `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.
affects: All
gotchaTools 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.
affects: All
Errors
Common errors & fixes
aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host 127.0.0.1:5000 ssl:False [Connection refused]
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.
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'
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.
Upgrade
Version history
1.1.0latest on PyPI · released May 18, 2026
Audit
Dependencies
aiohttprequiredRequired for asynchronous HTTP requests.
deprecatedrequiredUsed for marking deprecated features.
google-authrequiredRequired for Google authentication mechanisms.
pydanticrequiredUsed for data validation and settings management.
requestsrequiredRequired for synchronous HTTP requests (if used).
Agent activity
37 hits · last 30 days
node
30
OpenAI (training)
1
Resources
toolbox-core — pip install toolbox-core · libregistry