Groups

A Group is a single named collection that scopes MCP primitives together — currently tools and prompts, with more (such as resources) planned. Where a Toolset groups only tools, a group bundles these primitives under one name and one MCP endpoint, and carries a description that describes the collection.

Connecting to a group's endpoint (/mcp/{name}) scopes the corresponding MCP list methods (such as tools/list and prompts/list) to that group.

Defining Groups

Declare a group as a kind: group document in your configuration file. A group has the following fields:

* name is required for every named group. The single default group omits it.

As Toolbox adds support for more MCP primitives, groups will gain corresponding fields (for example, resources).

kind: group
name: data_analyst
description: Tools and prompts for exploratory data analysis.
tools:
  - list_tables
  - execute_sql
prompts:
  - summarize_results
---
kind: group
name: admin
description: Administrative operations.
tools:
  - create_user
  - list_users

The default group

A single default (nameless) group always exists and contains all configured primitives (every tool and prompt). Connecting to the default MCP endpoint (/mcp) returns everything.

You may declare a kind: group document with no name to set a description for the default group. Because the default group always contains everything, it cannot declare tools, prompts, or any other primitive list:

kind: group
description: All tools and prompts available on this server.

Validation rules

At startup, Toolbox validates groups:

• Unique names. A named group must have a unique name that satisfies the standard name rules (alphanumeric characters, underscores, and hyphens).
• One default group. Declaring more than one nameless group is an error.
• Default group restrictions. The default group may set only a description; declaring tools, prompts, or any other primitive list on it is an error.
• No duplicate names across toolsets and groups. A kind: toolset is parsed as a group, so defining the same name as both a kind: toolset and a kind: group is a duplicate-name error.

Relationship to toolsets

Groups are a superset of toolsets: a toolset is equivalent to a tools-only group. Existing kind: toolset configurations still load — Toolbox parses every toolset as a group — but that parity is not exact, so review the differences below before assuming a toolset behaves as it did:

• A toolset has no description of its own, so one written on a kind: toolset is dropped rather than promoted, and Toolbox logs a warning. To give a collection a description, declare it as a kind: group.
• Unrecognized fields on a toolset are rejected at startup instead of being silently ignored.
• Declaring the same name as both a kind: toolset and a kind: group is a duplicate-name error; previously the group silently took precedence.

We recommend migrating to a kind: group even for tools-only collections, so the configuration matches what Toolbox actually loads and can grow to scope prompts (and, in the future, other primitives) alongside tools. See Toolsets for more.

To convert existing toolsets to groups automatically, run the migrate command. It rewrites both nested toolsets: blocks and already-flat kind: toolset documents to kind: group:

toolbox migrate --config tools.yaml

Use --dry-run to preview the changes without writing them.