Skip to content

feat: Add setup-mcp-toolbox skill and directory structure #91

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
akangsha7 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: Add setup-mcp-toolbox skill and directory structure #91

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
97 changes: 97 additions & 0 deletions skills/setup-mcp-toolbox/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
---
name: setup-mcp-toolbox
description: A skill dedicated to downloading, setting up, and running the MCP Toolbox server. Focuses on binary delivery, OS-specific environment setup, and running the server instance using prebuilt configurations.
---

## Setup Toolbox Instructions

You are an expert at installing and bootstrapping the MCP Toolbox. When this skill is active, you MUST follow these phases in order:

### Phase 1: Discovery & Clarification
Determine the user's OS and preferred method. Use the latest version from the [releases page](https://github.com/googleapis/genai-toolbox/releases) (defaulting to `v0.28.0`).
Comment thread
akangsha7 marked this conversation as resolved.
Confirm the user's preferred installation method. Provide recommendations based on the user's setup.
* **The "Ambiguity Check"**: If a user asks to "Setup toolbox," you must prompt: *"I can set this up in three ways. Would you prefer a Local Binary (fastest), a Docker Container (isolated), or a Go SDK scaffold (for development)?"*

### Phase 2: Environment Probing & Download
Once a method is chosen, verify that the necessary environment is available. If a prerequisite is missing, provide instructions to install it:
* **For Homebrew**: Run `brew --version`. If missing, install via `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`.

@helloeve helloeve Mar 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

This likely won't work for Windows

* **For Docker**: Run `docker --version`. If missing, install [Docker Desktop](https://www.docker.com/products/docker-desktop/).
* **For Go**: Run `go version`. If missing, install via [go.dev/doc/install](https://go.dev/doc/install).
* **For NPX**: Ensure Node.js is installed (`node -v`).
Comment thread
akangsha7 marked this conversation as resolved.
* **For Binary**: No additional prerequisites (other than `curl`).

@helloeve helloeve Mar 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

there are 5 approaches listed here, but the instruction in L13 mentioned 3 ways (without homebrew & npx), we should make this consistent


If the user chose **Local Binary**, intelligently identify the OS/Architecture and execute the download. Use the latest version from the releases page:

#### A. Binary Installation
* **Linux (AMD64)**:
`curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox && chmod +x toolbox`
Comment thread
akangsha7 marked this conversation as resolved.
* **macOS (Apple Silicon)**:
`curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/arm64/toolbox && chmod +x toolbox`
* **macOS (Intel)**:
`curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/amd64/toolbox && chmod +x toolbox`
* **Windows (PowerShell)**:
`curl.exe -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v$VERSION/windows/amd64/toolbox.exe"`

#### B. Alternative Methods
* **NPX (Quickstart)**: For experimentation, run `npx @toolbox-sdk/server --prebuilt [database]`.

@helloeve helloeve Mar 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

similar to the previous comment, npx and homebrew doesn't seem to be something covered from If a user asks to "Setup toolbox," you must prompt: *"I can set this up in three ways. Would you prefer a Local Binary (fastest), a Docker Container (isolated), or a Go SDK scaffold (for development)?

* **Homebrew (macOS/Linux)**: Execute `brew install mcp-toolbox`.
* **Docker**: Execute `docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION`.
* **Source (Go)**: Run `go install github.com/googleapis/genai-toolbox@v$VERSION`.

### Phase 3: No Configuration (Prebuilt Servers Only)
This core setup skill STRICTLY utilizes prebuilt servers to establish a baseline running state. **Do NOT generate a `tools.yaml` file.**

@helloeve helloeve Mar 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

This will prevent the follow-up ./toolbox --ui


**CRITICAL SECURITY RULE:** NEVER ask the user to type their database password, host, or user details into this chat.

1. **Database Selection**: Ask the user which supported database they plan to connect to (e.g., Postgres, MySQL, Neo4j, Looker, etc.).

@helloeve helloeve Mar 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

How do we make the agent aware what are the supported databases? Especially for postgres, it could be cloudsql pg, alloydb pg, or local pg, and they may expect different set of parameters.

2. **Environment Variable Instructions**: Once they select a database, provide them with the exact terminal commands to set their credentials locally.

@helloeve helloeve Mar 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Similar to the question above, how would we expect the agent to know what are the right values if they choose something like Spanner?

* *Example for Mac/Linux (Bash/Zsh):*
```bash
export POSTGRES_USER="your_username"
export POSTGRES_PASSWORD="your_password"
export POSTGRES_DATABASE="your_database"
export POSTGRES_HOST="host address like 127.0.0.1"
export POSTGRES_PORT="port number like 5432"
```
* *Example for Windows (PowerShell):*
```powershell
$env:POSTGRES_USER="your_username"
$env:POSTGRES_PASSWORD="your_password"
$env:POSTGRES_DATABASE="your_database"
$env:POSTGRES_HOST="host address like 127.0.0.1"
$env:POSTGRES_PORT="port number like 5432"
```

@helloeve helloeve Mar 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Are we expecting the user to run these command themself? If so, I am not sure if the next phase will be able to pick it up without restarting the session & potentially refresh the terminal running Gemini CLI

3. **Specialized Skills for Customization**: Explicitly advise the user: *"This setup uses a prebuilt server for immediate connectivity. If you need to write custom SQL tools, configure authentication (AuthServices), or define custom prompts, please let me know so I can activate the specialized database skill (e.g., `config-mcp-toolbox-postgres`) to help you generate a custom `tools.yaml`."*

@helloeve helloeve Mar 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Shall we hold on this change before we actually have the real skill there?


### Phase 4: Execution
Start the MCP server using the prebuilt flag and verify standard output for a successful initialization signal.
* **Command**: `./toolbox --prebuilt [database] --stdio`

@helloeve helloeve Mar 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

  1. how would the agent know what is the right value for [database]? The user may type something like Cloud Sql mysql -- and we should map that to the correct prebuilt tool for supporting it

  2. This will likely not work for container based approach / npx

* **Dynamic Reloading**: Enabled by default. To disable it for static environments, append the `--no-reload` flag.
* **Stopping**: Instruct the user to use `ctrl+c` (SIGINT) to terminate the process.

@helloeve helloeve Mar 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

In Gemini CLI - this will terminate gemini cli rather than the toolbox process started by Gemini CLI bash tool (unless you focus on the interactive terminal first), I suspect this would also likely won't work smoothly for other agent framwork


### Phase 5: Gemini CLI Integration (Optional)
Ask the user: *"Would you like to integrate the Toolbox with your Gemini CLI settings?"*
Upon confirmation, provide the following JSON for them to append to `~/.gemini/settings.json`:

```json
{
"mcpServers": {
"toolbox": {
"command": "mcp-toolbox",

@helloeve helloeve Mar 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

this likely won't work, at least this shall be the absolute path to the toolbox binary that got downloaded, or some steps to have that added into the environment variable -- and again this would likely be different depends on the installation

"args": ["--prebuilt", "[database]", "--stdio"]
}
}
}
```

### Phase 6. Launching Toolbox UI
To test tools and toolsets interactively (including authorized parameters):
* Execute: `./toolbox --ui`

@helloeve helloeve Mar 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Two comments:

  1. This will likely fail as from the instructions above there won't be yaml produced (as it focused on prebuilt tools)
  2. This may not work for the docker & SDK path -- if the user choose that path, there is likely some other setups needed for launching it?

* Direct the user to the local web interface (typically `http://127.0.0.1:5000/`) to interact with the UI.

### Phase 7. Verification, Testing & Telemetry
* **Logging**: Customize output with `--log-level [debug|info|warn|error]` and `--logging-format [standard|json]`.
* **Telemetry**: Toolbox supports OpenTelemetry. Enable exporting to Google Cloud (`--telemetry-gcp`) or OTLP (`--telemetry-otlp="endpoint"`).
* **MCP Inspector**: Use `npx @modelcontextprotocol/inspector` to test connectivity (SSE, Streamable HTTP, or STDIO) and tools interactively.
* **Help**: Run `./toolbox help` for a full list of available flags and commands.
* **Verification**: Check that the server responds at `http://127.0.0.1:5000/`.
Empty file added skills/setup-mcp-toolbox/assets/.gitkeep
View file
Open in desktop
Comment thread
akangsha7 marked this conversation as resolved.
Empty file.
Empty file added skills/setup-mcp-toolbox/references/.gitkeep
View file
Open in desktop
Empty file.
Empty file added skills/setup-mcp-toolbox/scripts/.gitkeep
View file
Open in desktop
Empty file.
Loading