Skip to content

07-groups.md

Latest commit

 

History

History
159 lines (111 loc) · 5.99 KB

07-groups.md

File metadata and controls

159 lines (111 loc) · 5.99 KB
Raw

Groups

Groups are a logical abstraction for organizing related MCP servers, Agent Skills, and AI-tool plugins. They provide a shared organizational model without merging the distinct workload, skill, and plugin lifecycles.

Concept

A group is a named collection of MCP servers and may also record Agent Skill and AI-tool plugin membership for the same purpose or use case.

Examples:

  • data-pipeline - Data ingestion, transformation, storage tools
  • development - Code analysis, testing, deployment tools
  • research - Web search, document retrieval, summarization tools

Benefits:

  • Organizational structure for managing multiple servers
  • Client configuration (configure clients to use all servers in a group)
  • Foundation for future aggregation features
  • Logical grouping for access control

Architecture

graph TB
    Group[Group: data-pipeline]
    Group --> W1[Workload 1<br/>data-reader]
    Group --> W2[Workload 2<br/>data-processor]
    Group --> W3[Workload 3<br/>data-storage]

    W1 --> Container1[Container]
    W2 --> Container2[Container]
    W3 --> Remote[Remote MCP]

    style Group fill:#ba68c8
    style W1 fill:#90caf9
    style W2 fill:#90caf9
    style W3 fill:#90caf9
Loading

Implementation

RunConfig Field

Implementation: pkg/runner/config.go

{
  "name": "data-reader",
  "group": "data-pipeline",
  "image": "ghcr.io/example/data-reader:latest"
}

Group Operations

Groups support standard lifecycle operations: create, list, and remove. Workloads can be assigned to groups at creation time using the --group flag. Moving workloads between groups is currently only supported internally (e.g., when removing a group) and is not exposed as a user-facing CLI command. When removing a group, workloads are by default moved to the default group rather than deleted.

Implementation:

  • CLI commands: cmd/thv/app/group.go
  • Group manager: pkg/groups/
  • Workload integration: pkg/workloads/manager.go

Skill and Plugin Membership

The shared group record has Skills []string and Plugins []string fields in addition to workload membership. A skill or plugin install can add its name to a group; list operations can filter on that membership; uninstall removes the name from all groups. These updates participate in each service's rollback so a failed install or uninstall does not leave stale membership.

Groups organize these resources only. A grouped plugin is still materialized by the plugin service, and plugin-declared MCP or LSP servers do not become ToolHive workloads. See Skills System and Plugins System for lifecycle details.

Registry Groups

Registry groups are predefined collections of servers that can be deployed together as a unit. These groups are defined in the registry schema and support both container-based and remote MCP servers.

Architecture:

  • Registry groups are defined in the registry schema alongside individual servers
  • Groups can contain heterogeneous workload types (containers + remote servers)
  • Group deployment creates a runtime group with all member servers
  • Each server maintains its individual identity and configuration

Implementation: github.com/stacklok/toolhive-core/registry/types/registry_types.go

Use case: Deploy complete stacks (e.g., a full data processing pipeline) with a single command, ensuring all required components are available together.

Note: The default registry currently contains no predefined groups. This feature is available for custom registries or future additions to the default registry.

Client Configuration Integration

Groups provide a logical boundary for client configuration. The client manager can configure MCP clients with all servers belonging to a specific group, simplifying setup when multiple related servers need to be available to a client.

Architecture:

  • Client manager reads group membership from workload metadata
  • All servers in a group can be added to client configuration as a unit
  • Group membership is maintained in client configuration for organizational purposes

Implementation: pkg/client/

Use Cases

1. Related Services

Scenario: Multiple MCP servers that work together

Example: Data processing pipeline

  • data-reader - Reads from various sources
  • data-transformer - Transforms data formats
  • data-writer - Writes to destinations

Group: data-pipeline

2. Environment Separation

Scenario: Same tools in different environments

Groups:

  • production - Production servers
  • staging - Staging servers
  • development - Dev servers

3. Team Organization

Scenario: Different teams manage different servers

Groups:

  • backend-team - Backend development tools
  • frontend-team - Frontend development tools
  • data-team - Data analysis tools

Virtual MCP Integration

Groups are the foundation for Virtual MCP Servers. A VirtualMCPServer references an MCPGroup and aggregates all backends in that group into a single unified interface.

See Virtual MCP Server Architecture for details on:

  • Backend discovery from groups
  • Tool aggregation and conflict resolution
  • Composite tool workflows

Future Features

Groups may serve as the foundation for additional features:

  • Group-level policies: Apply authorization at group level
  • Group metrics: Aggregate telemetry from all group members
  • Group health: Overall health status of group

Related Documentation