{"id":9363,"library":"toolbox-core","title":"MCP Toolbox Core SDK","description":"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.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/googleapis/mcp-toolbox-sdk-python","tags":["AI","Generative AI","Tools","SDK","Google Cloud","Toolbox","Client","Orchestration"],"install":[{"cmd":"pip install toolbox-core","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for asynchronous HTTP requests.","package":"aiohttp","optional":false},{"reason":"Used for marking deprecated features.","package":"deprecated","optional":false},{"reason":"Required for Google authentication mechanisms.","package":"google-auth","optional":false},{"reason":"Used for data validation and settings management.","package":"pydantic","optional":false},{"reason":"Required for synchronous HTTP requests (if used).","package":"requests","optional":false}],"imports":[{"note":"The primary client for interacting with the MCP Toolbox service.","symbol":"ToolboxClient","correct":"from toolbox_core import ToolboxClient"}],"quickstart":{"code":"import asyncio\nimport os\nfrom toolbox_core import ToolboxClient\n\nasync def main():\n    # Replace with the actual URL where your Toolbox service is running.\n    # It's recommended to use an environment variable for the host in production.\n    toolbox_host = os.environ.get(\"TOOLBOX_SERVICE_URL\", \"http://127.0.0.1:5000\")\n    print(f\"Connecting to Toolbox service at: {toolbox_host}\")\n\n    try:\n        async with ToolboxClient(toolbox_host) as toolbox:\n            # Assuming 'get_weather' is a tool defined and exposed by your Toolbox service.\n            # The tool name must match a tool configured on the running Toolbox server.\n            weather_tool = await toolbox.load_tool(\"get_weather\")\n            print(\"Tool 'get_weather' loaded successfully.\")\n\n            # Invoke the loaded tool with its expected parameters.\n            result = await weather_tool(location=\"London\")\n            print(f\"Weather in London: {result}\")\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n        print(\"Ensure the MCP Toolbox server is running and accessible at the specified URL.\")\n        print(\"Refer to the MCP Toolbox Server Getting Started Guide for setup instructions (e.g., https://github.com/googleapis/mcp-toolbox).\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0 (and future minor versions of the core service)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host 127.0.0.1:5000 ssl:False [Connection refused]"},{"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.","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.","error":"toolbox_core.exceptions.ToolboxError: Tool 'non_existent_tool' not found on the server."},{"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.","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.","error":"TypeError: 'weather_tool' got an unexpected keyword argument 'city'"}]}