Support shared MCP definitions to reduce duplication and enable consistency

[ThePlenkov]

Problem

When using the same MCP (Model Context Protocol) tools across multiple agents, the configuration must be duplicated for each agent. This creates maintenance challenges:

agents:
  coordinator:
    toolsets:
      - type: mcp
        command: npx
        args: ["-y", "@example/tool-mcp@^1.2.3"]
        defer: true
        timeout: 30000
        env:
          MCP_TIMEOUT: "30000"

  specialist_1:
    toolsets:
      - type: mcp
        command: npx
        args: ["-y", "@example/tool-mcp@^1.2.3"]  # ← Duplicated
        defer: true
        timeout: 30000
        env:
          MCP_TIMEOUT: "30000"  # ← Duplicated

Issues with duplication:

1. Consistency Risk: Easy to miss updating one agent's configuration
2. Maintenance Burden: Changes must be made in multiple places
3. Version Management: Hard to coordinate version updates across agents
4. Error Prone: Inconsistencies can cause subtle bugs (e.g., one agent times out)

Solution

Support shared MCP definitions with references:

mcps:
  search_tool:
    command: npx
    args: ["-y", "@example/tool-mcp@^1.2.3"]
    defer: true
    timeout: 30000
    env:
      MCP_TIMEOUT: "30000"

agents:
  coordinator:
    toolsets:
      - type: mcp
        ref: search_tool

  specialist_1:
    toolsets:
      - type: mcp
        ref: search_tool

  specialist_2:
    toolsets:
      - type: mcp
        ref: search_tool

Benefits

• ✅ Single Source of Truth: Define MCP configuration once
• ✅ Consistency: All agents use identical configuration
• ✅ Easy Updates: Change once, applies everywhere
• ✅ Version Pinning: Control rollouts of tool updates
• ✅ Cleaner Config: Less repetition, easier to read
• ✅ Configuration Validation: Easier to detect mismatches

Implementation Details

Registry Structure

mcps:
  <tool_name>:
    command: <command>
    args: [<array_of_args>]
    defer: <boolean>
    timeout: <milliseconds>
    env:
      <VAR>: <value>

Reference Usage

toolsets:
  - type: mcp
    ref: <tool_name>

Backward Compatibility

• Existing inline MCP definitions continue to work
• New ref: parameter optional
• No breaking changes
• Allow both inline and reference-based in same config

Override Support (Optional)

toolsets:
  - type: mcp
    ref: search_tool
    timeout: 60000  # Override specific property

Use Cases

1. Multi-agent Coordination: Teams of specialized agents share common tools
2. Consistency at Scale: Ensure all agents timeout at same interval
3. Version Management: Roll out tool updates systematically
4. Configuration Clarity: Reduce duplication, improve readability

Acceptance Criteria

• Support mcps: registry section in configuration
• Support ref: parameter to reference MCPs by name
• Support optional property overrides when using ref:
• Clear error messages for invalid references
• Backward compatible with inline MCP definitions
• Documentation with examples
• Tests cover reference resolution and overrides