Group Management

Overview

Group Management in MCPHub allows you to organize your MCP servers into logical collections based on functionality, use case, or access requirements. This enables fine-grained control over which tools are available to different AI clients and users.

Core Concepts

What are Groups?

Groups are named collections of MCP servers that can be accessed through dedicated endpoints. Instead of connecting to all servers at once, AI clients can connect to specific groups to access only relevant tools.

Benefits of Groups

Focused Tool Access: AI clients see only relevant tools for their use case
Better Performance: Reduced tool discovery overhead
Enhanced Security: Limit access to sensitive tools
Improved Organization: Logical separation of functionality
Simplified Management: Easier to manage related servers together

Creating Groups

Via Dashboard

Navigate to Groups Section: Click “Groups” in the main navigation
Click “Create Group”: Start the group creation process
Fill Group Details:
- Name: Unique identifier for the group
Add Servers: Select servers to include in the group

Bulk Capability Selection

Expand a server in the group editor to search tools, prompts, or resources by name (resource URI) or description. Search is a case-insensitive substring match, not a glob or regular expression. Select visible, Deselect visible, and Invert visible affect only the filtered items; other selections stay unchanged. Tools also support explicit readOnlyHint, destructiveHint, and idempotentHint filters. Switch between the flat list and risk groups (Read/Create/Update/Delete/Other) for per-group counters and batch selection. Classification uses upstream hints and name heuristics as an editing aid, not a safety guarantee. Group actions also respect the current filters. These actions modify this group’s selection only, not the server’s global enabled state. Deselecting tools clears their Smart Routing pins. Editing an explicit subset stores a snapshot of tool names; it does not automatically select future tools. The existing whole-section Select All retains the dynamic all selection behavior.

Via API

Create groups programmatically:

curl -X POST http://localhost:3000/api/groups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "name": "web-automation",
    "servers": ["playwright", "fetch"]
  }'

Group Types and Use Cases

Web Automation Group

Purpose: Browser automation and web scrapingServers:

playwright: Browser automation
fetch: HTTP requests and web scraping
selenium: Alternative browser automation

Use Cases:

Automated testing
Data collection
Web monitoring
Content analysis

Endpoint: http://localhost:3000/mcp/web-automation

Data Processing Group

Purpose: Data manipulation and analysisServers:

sqlite: Database operations
filesystem: File operations
spreadsheet: Excel/CSV processing

Use Cases:

Data analysis
Report generation
File processing
Database queries

Endpoint: http://localhost:3000/mcp/data-processing

Communication Group

Purpose: Messaging and collaborationServers:

slack: Slack integration
discord: Discord bot
email: Email sending
sms: SMS notifications

Use Cases:

Team notifications
Customer communication
Alert systems
Social media management

Endpoint: http://localhost:3000/mcp/communication

Development Group

Purpose: Software development toolsServers:

github: GitHub operations
gitlab: GitLab integration
docker: Container management
kubernetes: K8s operations

Use Cases:

Code deployment
Repository management
CI/CD operations
Infrastructure management

Endpoint: http://localhost:3000/mcp/development

AI/ML Group

Purpose: Machine learning and AI toolsServers:

openai: OpenAI API integration
huggingface: Hugging Face models
vector-db: Vector database operations

Use Cases:

Model inference
Data embeddings
Natural language processing
Computer vision

Endpoint: http://localhost:3000/mcp/ai-ml

Group Endpoints

Accessing Groups

Each group gets its own MCP endpoint:

HTTP MCP
SSE (Legacy)

http://localhost:3000/mcp/{group-name}

Examples:

http://localhost:3000/mcp/web-tools
http://localhost:3000/mcp/data-processing
http://localhost:3000/mcp/communication

http://localhost:3000/sse/{group-name}

Examples:

http://localhost:3000/sse/web-tools
http://localhost:3000/sse/data-processing
http://localhost:3000/sse/communication

Group Tool Discovery

When connecting to a group endpoint, AI clients will only see tools from servers within that group:

# List tools in web-tools group
curl -X POST http://localhost:3000/mcp/web-tools \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Response will only include tools from fetch and playwright servers.

Group instructions

MCP clients receive an optional instructions string from the initialize response, and most of them add it to the model’s system prompt. It is the place to tell the model when to use a connection, for example to prefer the group’s fetch tool over a built-in one, or which tool to try when another fails. Set it with the group’s instructions field (dashboard, POST/PUT /api/groups, or the group entry in mcp_settings.json). It is sent on:

/mcp/{group}: for a group with several servers, the group’s text alone. For a single-server group, the group’s text followed by the server’s own upstream instructions (a single-server group already forwarded those).
/mcp/$smart/{group}: the group’s text.

Bare /mcp/$smart, the global route and server-name routes have no group, so they send no group instructions. Clients read instructions once per session: reconnect after changing them.

{
  "name": "web",
  "instructions": "For web pages use fetch first. If it fails (403, blocked, empty or JavaScript-only page), retry the same URL with firecrawl_scrape.",
  "servers": ["fetch", "firecrawl"]
}

Dynamic Group Management

Adding Servers to Groups

Dashboard
API

Navigate to the group in the dashboard
Click “Manage Servers”
Select additional servers to add
Click “Save Changes”

curl -X POST http://localhost:3000/api/groups/web-tools/servers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"serverId": "new-server"}'

Removing Servers from Groups

Dashboard
API

Navigate to the group in the dashboard
Click “Manage Servers”
Unselect servers to remove
Click “Save Changes”

curl -X DELETE http://localhost:3000/api/groups/web-tools/servers/server-name \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Best Practices

Group Organization

Organize by Use Case: Group servers based on what users want to accomplish, not just technical similarity.

Keep Groups Focused: Avoid creating groups with too many diverse tools. Smaller, focused groups are more useful.

Use Descriptive Names: Choose names that clearly indicate the group’s purpose and contents.

Performance Optimization

Balance Group Size: Very large groups may have slower tool discovery. Consider splitting into smaller groups.

Monitor Usage: Use analytics to identify which groups are heavily used and optimize accordingly.

Troubleshooting

Group Not Accessible

Check:

User has proper permissions
Group exists and is active
Servers in group are running
Network connectivity

Solutions:

Verify user group membership
Check group configuration
Test individual server connections
Review access logs

Tools Missing from Group

Possible causes:

Server not properly added to group
Server is not running
Tool discovery failed
Caching issues

Debug steps:

Verify server is in group configuration
Check server status
Force refresh tool discovery
Clear group cache

Group Performance Issues

Common issues:

Too many servers in group
Slow server responses
Network latency
Resource constraints

Optimizations:

Split large groups
Monitor server performance
Implement request caching
Use connection pooling

Next Steps

Smart Routing

AI-powered tool discovery across groups

Authentication

User management and access control

API Reference

Complete group management API

Configuration

Advanced group configuration options

New groups default to private. Set visibility to private (owner and admins), group (owner, admins, and usernames in sharedWithUsers), or public (all users). The dashboard labels group as Shared. Save a group before choosing users in its edit form. Only the owner and admins can change or delete a group, including its server configuration. For user-authenticated MCP requests, access requires both group and server visibility, subject to the legacy group behavior described below. Sharing a group never grants access to a server the user cannot otherwise access. These checks also apply to SSE and $smart/<group> routes, and group access is checked again for existing sessions. User bearer keys (kind: 'user') inherit their owner’s live permissions. By default, accessType: 'all' means the owner’s permitted resources, not unrestricted system access. Users can narrow a key to accessType: 'groups' with allowedGroups; the API saves group IDs. Such keys can use only the selected group endpoints (including $smart/<group>), never global or direct-server endpoints. Group scope intersects with user visibility and group capability selections. See Bearer keys. System bearer keys (kind: 'system') use their configured operator scope without applying user-based group or server visibility. A system key with accessType: 'all' can therefore access private groups and servers; scoped system keys remain limited to their configured scope. System keys do not establish a user identity or provide personal credentials. Group lists, details, and server configuration responses omit servers the caller cannot access, including their names, aliases, and capability selections. When an owner replaces the visible server selection, inaccessible existing entries are preserved; an admin can manage the complete group.

Upgrading existing groups

Groups without a visibility value retain legacy endpoint access: users who know the endpoint can use servers they are authorized to access. Their directory visibility remains owner/admin only. The dashboard flags these groups for an explicit visibility choice; saving unrelated fields does not silently make them private or public. Database mode adds a unique constraint on group names. Startup checks for duplicate names before schema synchronization and stops with the conflicting names/counts if any exist. Resolve duplicates manually before restarting; MCPHub does not rename or delete them. Group names remain globally reserved, including private groups. Contact an administrator for conflicts you cannot resolve from your directory.

Keep original tool names

Enable Keep original tool names for a server in a group’s capability settings to expose tools using their upstream names, for example fetch_url instead of fetch-fetch_url. In JSON settings or the groups API, set preserveToolNames: true on that server’s group entry. This applies to both the group route and $smart/<group>; prompts and resources keep their existing naming behavior. The setting defaults to false, and an empty Exposed Name continues to fall back to the server name. Names must be unique across the group’s visible tools, including tools from servers that still use a prefix. If names collide, tool discovery and group tool calls fail with an ambiguity error; select fewer tools or restore prefixes to resolve the conflict. The names search_tools, describe_tool, and call_tool are reserved for Smart Routing and cannot be exposed when this setting is enabled. Name checks run against the currently available catalog, so a newly connected server can introduce a conflict.

Get Started

Core Features

Configuration

Development

Overview

Core Concepts

What are Groups?

Benefits of Groups

Creating Groups

Via Dashboard

Bulk Capability Selection

Via API

Group Types and Use Cases

Group Endpoints

Accessing Groups

Group Tool Discovery

Group instructions

Dynamic Group Management

Adding Servers to Groups

Removing Servers from Groups

Best Practices

Group Organization

Performance Optimization

Troubleshooting

Next Steps

Smart Routing

Authentication

API Reference

Configuration

Upgrading existing groups

Keep original tool names

​Overview

​Core Concepts

​What are Groups?

​Benefits of Groups

​Creating Groups

​Via Dashboard

​Bulk Capability Selection

​Via API

​Group Types and Use Cases

​Group Endpoints

​Accessing Groups

​Group Tool Discovery

​Group instructions

​Dynamic Group Management

​Adding Servers to Groups

​Removing Servers from Groups

​Best Practices

​Group Organization

​Performance Optimization

​Troubleshooting

​Next Steps

Smart Routing

Authentication

API Reference

Configuration

​Visibility and sharing

​Upgrading existing groups

​Keep original tool names

Overview

Core Concepts

What are Groups?

Benefits of Groups

Creating Groups

Via Dashboard

Bulk Capability Selection

Via API

Group Types and Use Cases

Group Endpoints

Accessing Groups

Group Tool Discovery

Group instructions

Dynamic Group Management

Adding Servers to Groups

Removing Servers from Groups

Best Practices

Group Organization

Performance Optimization

Troubleshooting

Next Steps

Visibility and sharing

Upgrading existing groups

Keep original tool names