Organizing MCP servers with groups
As your MCP server usage grows, managing multiple servers becomes increasingly complex. Groups provide a way to organize servers logically and control which tools are available to different clients.
The problem groups solve
Without groups, all your MCP servers live in a single pool. This creates challenges:
- Tool overload: AI clients see every tool from every server, making it harder to select the right one
- No separation of concerns: Development tools mix with production tools
- One-size-fits-all access: Every client gets access to everything, even when they only need a subset
Groups address these issues by letting you organize servers into logical collections and control which clients can access each collection.
When to use groups
Groups are most valuable when you need to:
- Separate environments: Keep development, staging, and production servers isolated so you don't accidentally use production tools during development
- Organize by project: Give each team access to the tools they need without cluttering their workspace with irrelevant servers
- Customize client access: Configure different AI clients with different tool sets based on their purpose
- Reduce context for AI: Limit the tools available to an AI client so it can make better decisions about which tool to use
When groups aren't necessary
Groups add organizational overhead, so they're not always the right choice:
- Single server setups: If you're running just one or two MCP servers, groups don't provide much benefit
- Universal access needs: If all clients need access to all servers, a single default group works fine
- Simple personal use: For individual developers with straightforward needs, the default group is often sufficient
Organizational patterns
Here are common ways teams organize their groups:
Environment-based groups
Separate servers by deployment environment to prevent mixing development and production contexts:
| Group | Purpose |
|---|---|
| development | Experimental tools, local databases, test APIs |
| staging | Pre-production testing with realistic data |
| production | Live systems with appropriate access controls |
This pattern is useful when:
- You run the same MCP server with different configurations per environment
- You want to prevent accidental production access during development
- Different team members need different environment access
This pattern works well when:
- Teams have distinct tool requirements
- You want to reduce clutter in each team's AI client
- Different teams work on different parts of your system
Project-based groups
Create groups for specific projects or products:
| Group | Servers |
|---|---|
| mobile-app | Firebase, app store tools, mobile analytics |
| web-platform | CMS tools, CDN management, web analytics |
| internal-tools | Admin dashboards, reporting tools |
This approach helps when:
- Projects have unique tool requirements
- You want focused AI assistance for specific work contexts
- Multiple teams contribute to the same project
Groups and client access
One of the most powerful aspects of groups is controlling which AI clients can access which servers. When you configure a client for a specific group, that client only sees servers in that group.
This matters because:
- Better AI performance: Fewer tools means the AI can make more confident tool selections
- Appropriate access: Different clients can have different capabilities based on their purpose
- Reduced noise: Developers see only the tools relevant to their current work
For example, you might configure:
- Visual Studio Code with access to your development group for day-to-day coding
- Claude Desktop with access to your production group for operational tasks
- GitHub Copilot with access to a restricted group for code review
A single client can access multiple groups. This is useful when you need tools from several areas, like a developer who works across frontend and backend.
Default group behavior
Every ToolHive installation has a default group that cannot be deleted. This
group serves as:
- The starting point: New servers go here unless you specify otherwise
- The fallback: Servers move here when their group is deleted
- The simple path: If you don't need organization, just use the default
You don't need to create custom groups to use ToolHive effectively. The default group works well for simple setups and individual use.
Designing your group structure
When planning your groups, consider:
- Start simple: Begin with the default group and add custom groups only when you feel the need for organization
- Match your workflow: Groups should reflect how you actually work, not an idealized structure
- Consider client configuration: Think about which clients need access to which servers
- Plan for growth: Choose a pattern that scales as you add more servers
Each server belongs to exactly one group. If you need the same MCP server in multiple groups (for example, a GitHub server in both development and production), run separate instances with different names and configurations.
Next steps
Now that you understand when and why to use groups, you can: