Connect via MCP Client

How to connect to Toolbox from a MCP Client.

Toolbox SDKs vs Model Context Protocol (MCP)

Toolbox now supports connections via both the native Toolbox SDKs and via Model Context Protocol (MCP). However, Toolbox has several features which are not supported in the MCP specification (such as Authenticated Parameters and Authorized invocation).

We recommend using the native SDKs over MCP clients to leverage these features. The native SDKs can be combined with MCP clients in many cases.

Protocol Versions

Toolbox currently supports the following versions of MCP specification:

Toolbox AuthZ/AuthN Not Supported by MCP

The auth implementation in Toolbox is not supported in MCP’s auth specification. This includes:

Connecting to Toolbox with an MCP client

Before you begin

Note

MCP is only compatible with Toolbox version 0.3.0 and above.

Install Toolbox version 0.3.0+.
Make sure you’ve set up and initialized your database.
Set up your tools.yaml file.

Connecting via Standard Input/Output (stdio)

Toolbox supports the stdio transport protocol. Users that wish to use stdio will have to include the --stdio flag when running Toolbox.

./toolbox --stdio

When running with stdio, Toolbox will listen via stdio instead of acting as a remote HTTP server. Logs will be set to the warn level by default. debug and info logs are not supported with stdio.

Note

Toolbox enables dynamic reloading by default. To disable, use the --disable-reload flag.

Connecting via HTTP

Toolbox supports the HTTP transport protocol with and without SSE.

Add the following configuration to your MCP client configuration:

{
  "mcpServers": {
    "toolbox": {
      "type": "sse",
      "url": "http://127.0.0.1:5000/mcp/sse",
    }
  }
}

If you would like to connect to a specific toolset, replace url with "http://127.0.0.1:5000/mcp/{toolset_name}/sse".

HTTP with SSE is only supported in version 2024-11-05 and is currently deprecated.

Add the following configuration to your MCP client configuration:

{
  "mcpServers": {
    "toolbox": {
      "type": "http",
      "url": "http://127.0.0.1:5000/mcp",
    }
  }
}

If you would like to connect to a specific toolset, replace url with "http://127.0.0.1:5000/mcp/{toolset_name}".

Using the MCP Inspector with Toolbox

Use MCP Inspector for testing and debugging Toolbox server.

Run Inspector with Toolbox as a subprocess:

npx @modelcontextprotocol/inspector ./toolbox --stdio

For Transport Type dropdown menu, select STDIO.
In Command, make sure that it is set to :./toolbox (or the correct path to where the Toolbox binary is installed).
In Arguments, make sure that it’s filled with --stdio.
Click the Connect button. It might take awhile to spin up Toolbox. Voila! You should be able to inspect your toolbox tools!

Run Toolbox.
In a separate terminal, run Inspector directly through npx:
```
npx @modelcontextprotocol/inspector
```
For Transport Type dropdown menu, select SSE.
For URL, type in http://127.0.0.1:5000/mcp/sse to use all tool or http//127.0.0.1:5000/mcp/{toolset_name}/sse to use a specific toolset.
Click the Connect button. Voila! You should be able to inspect your toolbox tools!

Run Toolbox.
In a separate terminal, run Inspector directly through npx:
```
npx @modelcontextprotocol/inspector
```
For Transport Type dropdown menu, select Streamable HTTP.
For URL, type in http://127.0.0.1:5000/mcp to use all tool or http//127.0.0.1:5000/mcp/{toolset_name} to use a specific toolset.
Click the Connect button. Voila! You should be able to inspect your toolbox tools!

Tested Clients

Client	SSE Works	MCP Config Docs
Claude Desktop	✅	https://modelcontextprotocol.io/quickstart/user#1-download-claude-for-desktop
MCP Inspector	✅	https://github.com/modelcontextprotocol/inspector
Cursor	✅	https://docs.cursor.com/context/model-context-protocol
Windsurf	✅	https://docs.windsurf.com/windsurf/mcp
VS Code (Insiders)	✅	https://code.visualstudio.com/docs/copilot/chat/mcp-servers

Last modified October 23, 2025: chore(main): release 0.18.0 (#1719) (3ca58b1)