Add top-level mcps section for reusable MCP server definitions

Introduce a top-level 'mcps' section in the agent config that allows
defining MCP server configurations once and referencing them by name
from agent toolsets. This eliminates duplication when multiple agents
use the same MCP server.

Agent toolsets reference definitions via 'ref: <name>'. Fields set on
the toolset override the definition; env maps are merged with toolset
values taking precedence on conflicts.

Definitions are validated at parse time using the existing Toolset
validation, rejecting nonsensical fields (e.g. shared, path) and
invalid source combinations.

Closes #1667

Assisted-By: cagent

Author: dgageot

agent-schema.json

@@ -48,6 +48,13 @@
         "$ref": "#/definitions/ModelConfig"
       }
     },
+    "mcps": {
+      "type": "object",
+      "description": "Map of reusable MCP server definitions. Define MCP servers here and reference them by name from agent toolsets to avoid duplication.",
+      "additionalProperties": {
+        "$ref": "#/definitions/MCPToolset"
+      }
+    },
     "rag": {
       "type": "object",
       "description": "Map of RAG (Retrieval-Augmented Generation) configurations",
@@ -683,6 +690,95 @@
       },
       "additionalProperties": false
     },
+    "MCPToolset": {
+      "type": "object",
+      "description": "Reusable MCP server definition. Define once at the top level and reference by name from agent toolsets.",
+      "properties": {
+        "command": {
+          "type": "string",
+          "description": "Command to run the MCP server (stdio transport)"
+        },
+        "args": {
+          "type": "array",
+          "description": "Arguments to pass to the command",
+          "items": {
+            "type": "string"
+          }
+        },
+        "ref": {
+          "type": "string",
+          "description": "Docker MCP reference (e.g., 'docker:context7')",
+          "pattern": "^docker:"
+        },
+        "remote": {
+          "$ref": "#/definitions/Remote",
+          "description": "Remote MCP server configuration (SSE/streamable-http transport)"
+        },
+        "config": {
+          "description": "MCP server configuration (for docker refs)"
+        },
+        "version": {
+          "type": "string",
+          "description": "Version/package reference for auto-installation"
+        },
+        "env": {
+          "type": "object",
+          "description": "Environment variables for the MCP server",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "tools": {
+          "type": "array",
+          "description": "Optional list of tools to expose from the MCP server",
+          "items": {
+            "type": "string"
+          }
+        },
+        "instruction": {
+          "type": "string",
+          "description": "Optional instruction for the tools"
+        },
+        "name": {
+          "type": "string",
+          "description": "Optional display name override for the MCP server"
+        },
+        "defer": {
+          "description": "Deferred loading configuration for tools from this MCP server",
+          "oneOf": [
+            {
+              "type": "boolean",
+              "description": "Set to true to defer all tools"
+            },
+            {
+              "type": "array",
+              "description": "Array of tool names to defer",
+              "items": {
+                "type": "string"
+              }
+            }
+          ]
+        }
+      },
+      "anyOf": [
+        {
+          "required": [
+            "command"
+          ]
+        },
+        {
+          "required": [
+            "remote"
+          ]
+        },
+        {
+          "required": [
+            "ref"
+          ]
+        }
+      ],
+      "additionalProperties": false
+    },
     "Toolset": {
       "type": "object",
       "description": "Tool configuration",
@@ -718,8 +814,7 @@
         },
         "ref": {
           "type": "string",
-          "description": "Reference to external tool (e.g., docker:context7)",
-          "pattern": "^docker:"
+          "description": "Reference to a Docker MCP tool (e.g., 'docker:context7') or a named MCP definition from the top-level 'mcps' section"
         },
         "config": {
           "description": "Tool-specific configuration"

examples/mcp-definitions.yaml

@@ -0,0 +1,78 @@
+#!/usr/bin/env docker agent run
+# yaml-language-server: $schema=../agent-schema.json
+
+# This example demonstrates how to use the top-level `mcps` section to define
+# MCP servers once and reference them across multiple agents, avoiding duplication.
+
+models:
+  model:
+    provider: anthropic
+    model: claude-sonnet-4-0
+    max_tokens: 64000
+
+# Define MCP servers once at the top level.
+# Each entry can use `command`, `remote`, or `ref` (just like inline MCP toolsets).
+mcps:
+  context7:
+    ref: docker:context7
+
+  github:
+    ref: docker:github
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+    tools:
+      - create_or_update_file
+      - search_repositories
+      - create_repository
+      - get_file_contents
+      - push_files
+      - create_issue
+      - create_pull_request
+      - list_issues
+
+agents:
+  root:
+    model: model
+    description: Lead developer
+    instruction: |
+      You are the lead developer. Coordinate the team.
+    sub_agents: [frontend, backend]
+    toolsets:
+      - type: filesystem
+      - type: think
+      # Reference the MCP definition by name — no need to repeat the full config.
+      - type: mcp
+        ref: context7
+      - type: mcp
+        ref: github
+
+  frontend:
+    model: model
+    description: Frontend engineer
+    instruction: |
+      You are a frontend engineer.
+    toolsets:
+      - type: filesystem
+      - type: shell
+      # Same MCP server, referenced by name.
+      - type: mcp
+        ref: context7
+      # Reference github MCP but override the tool list for this agent.
+      - type: mcp
+        ref: github
+        tools:
+          - get_file_contents
+          - search_repositories
+
+  backend:
+    model: model
+    description: Backend engineer
+    instruction: |
+      You are a backend engineer.
+    toolsets:
+      - type: filesystem
+      - type: shell
+      - type: mcp
+        ref: context7
+      - type: mcp
+        ref: github

pkg/config/config.go

@@ -113,6 +113,10 @@ func validateConfig(cfg *latest.Config) error {
 		return err
 	}
 
+	if err := resolveMCPDefinitions(cfg); err != nil {
+		return err
+	}
+
 	allNames := map[string]bool{}
 	for _, agent := range cfg.Agents {
 		allNames[agent.Name] = true

pkg/config/latest/types.go

@@ -21,11 +21,34 @@ type Config struct {
 	Agents      Agents                    `json:"agents,omitempty"`
 	Providers   map[string]ProviderConfig `json:"providers,omitempty"`
 	Models      map[string]ModelConfig    `json:"models,omitempty"`
+	MCPs        map[string]MCPToolset     `json:"mcps,omitempty"`
 	RAG         map[string]RAGConfig      `json:"rag,omitempty"`
 	Metadata    Metadata                  `json:"metadata"`
 	Permissions *PermissionsConfig        `json:"permissions,omitempty"`
 }
 
+// MCPToolset is a reusable MCP server definition stored in the top-level
+// "mcps" section. It is identical to a Toolset but skips the normal
+// Toolset.validate() call during YAML unmarshaling because the "type"
+// field is implicit (always "mcp") and the source (command/remote/ref)
+// is validated later during config resolution.
+type MCPToolset struct {
+	Toolset `json:",inline" yaml:",inline"`
+}
+
+func (m *MCPToolset) UnmarshalYAML(unmarshal func(any) error) error {
+	// Use a plain alias to avoid triggering Toolset.UnmarshalYAML
+	// (which calls validate and requires "type" to be set).
+	type alias Toolset
+	var tmp alias
+	if err := unmarshal(&tmp); err != nil {
+		return err
+	}
+	m.Toolset = Toolset(tmp)
+	m.Type = "mcp"
+	return m.validate()
+}
+
 type Agents []AgentConfig
 
 func (c *Agents) UnmarshalYAML(unmarshal func(any) error) error {

pkg/config/latest/validate.go

@@ -2,7 +2,6 @@ package latest
 
 import (
 	"errors"
-	"strings"
 )
 
 func (t *Config) UnmarshalYAML(unmarshal func(any) error) error {
@@ -139,10 +138,6 @@ func (t *Toolset) validate() error {
 		if count > 1 {
 			return errors.New("either command, remote or ref must be set, but only one of those")
 		}
-
-		if t.Ref != "" && !strings.Contains(t.Ref, "docker:") {
-			return errors.New("only docker refs are supported for MCP tools, e.g., 'docker:context7'")
-		}
 	case "a2a":
 		if t.URL == "" {
 			return errors.New("a2a toolset requires a url to be set")

pkg/config/mcps.go

@@ -0,0 +1,91 @@
+package config
+
+import (
+	"fmt"
+	"maps"
+	"strings"
+
+	"github.com/docker/cagent/pkg/config/latest"
+)
+
+// resolveMCPDefinitions resolves MCP definition references in agent toolsets.
+// When an agent toolset of type "mcp" has a ref that matches a key in the
+// top-level mcps section (rather than a "docker:" ref), the toolset is expanded
+// with the definition's properties. Any properties set directly on the toolset
+// override the corresponding definition properties.
+func resolveMCPDefinitions(cfg *latest.Config) error {
+	for name, def := range cfg.MCPs {
+		if err := validateMCPDefinition(name, &def.Toolset); err != nil {
+			return err
+		}
+	}
+
+	for i := range cfg.Agents {
+		agent := &cfg.Agents[i]
+		for j := range agent.Toolsets {
+			ts := &agent.Toolsets[j]
+			if ts.Type != "mcp" || ts.Ref == "" || strings.Contains(ts.Ref, "docker:") {
+				continue
+			}
+
+			def, ok := cfg.MCPs[ts.Ref]
+			if !ok {
+				return fmt.Errorf("agent '%s' references non-existent MCP definition '%s'", agent.Name, ts.Ref)
+			}
+
+			applyMCPDefaults(ts, &def.Toolset)
+		}
+	}
+
+	return nil
+}
+
+// validateMCPDefinition validates that a definition's ref uses the docker: prefix.
+// The basic source validation (exactly one of command/remote/ref) is already handled
+// by Toolset.validate() during YAML unmarshaling.
+func validateMCPDefinition(name string, def *latest.Toolset) error {
+	if def.Ref != "" && !strings.Contains(def.Ref, "docker:") {
+		return fmt.Errorf("MCP definition '%s': only docker refs are supported (e.g., 'docker:context7')", name)
+	}
+	return nil
+}
+
+// applyMCPDefaults fills empty fields in ts from def. Toolset values win.
+// Env maps are merged (toolset values take precedence on key conflicts).
+func applyMCPDefaults(ts, def *latest.Toolset) {
+	// Replace the definition-name ref with the actual source.
+	ts.Ref = def.Ref
+	if ts.Command == "" {
+		ts.Command = def.Command
+	}
+	if ts.Remote.URL == "" {
+		ts.Remote = def.Remote
+	}
+	if len(ts.Args) == 0 {
+		ts.Args = def.Args
+	}
+	if ts.Version == "" {
+		ts.Version = def.Version
+	}
+	if ts.Config == nil {
+		ts.Config = def.Config
+	}
+	if ts.Name == "" {
+		ts.Name = def.Name
+	}
+	if ts.Instruction == "" {
+		ts.Instruction = def.Instruction
+	}
+	if len(ts.Tools) == 0 {
+		ts.Tools = def.Tools
+	}
+	if ts.Defer.IsEmpty() {
+		ts.Defer = def.Defer
+	}
+	if len(def.Env) > 0 {
+		merged := make(map[string]string, len(def.Env)+len(ts.Env))
+		maps.Copy(merged, def.Env)
+		maps.Copy(merged, ts.Env)
+		ts.Env = merged
+	}
+}