feat: add optional working_dir to MCP and LSP toolset configs

- Add WorkingDir field to Toolset struct (pkg/config/latest/types.go)
- Validate that working_dir is only used with type 'mcp' or 'lsp'
- Resolve working_dir relative to agent's working directory at process start
- Propagate working_dir from top-level mcps: definitions to agent toolsets
- Add resolveToolsetWorkingDir helper in registry.go
- Add tests: validate_test.go, mcps_test.go, registry_test.go
- Add example: examples/toolset-working-dir.yaml
- Update agent-schema.json for Toolset and MCPToolset

Closes #2459

Assisted-By: docker-agent

Author: simonferquel-clanker

agent-schema.json

@@ -901,6 +901,10 @@
               }
             }
           ]
+        },
+        "working_dir": {
+          "type": "string",
+          "description": "Optional working directory for the MCP server process. Relative paths are resolved relative to the agent's working directory."
         }
       },
       "anyOf": [
@@ -1141,6 +1145,10 @@
         "version": {
           "type": "string",
           "description": "Package reference for auto-installation of MCP/LSP tool binaries. Format: 'owner/repo' or 'owner/repo@version'. Set to 'false' to disable auto-install for this toolset."
+        },
+        "working_dir": {
+          "type": "string",
+          "description": "Optional working directory for MCP/LSP toolset processes. Relative paths are resolved relative to the agent's working directory. Only valid for type 'mcp' or 'lsp'."
         }
       },
       "additionalProperties": false,

examples/toolset-working-dir.yaml

@@ -0,0 +1,29 @@
+#!/usr/bin/env docker agent run
+
+# Example: using working_dir for MCP and LSP toolsets
+#
+# Some language servers and MCP tools must be started from a specific directory.
+# For example, gopls must be started from the Go module root. Use `working_dir`
+# to configure the launch directory for any MCP or LSP toolset.
+#
+# `working_dir` is:
+#   - Optional (defaults to the agent's working directory when omitted)
+#   - Resolved relative to the agent's working directory if it is a relative path
+
+agents:
+  root:
+    model: openai/gpt-4o
+    description: Example agent demonstrating working_dir for MCP and LSP toolsets
+    instruction: |
+      You are a helpful coding assistant with access to language server and MCP tools
+      launched from their respective project directories.
+    toolsets:
+      # LSP server started from a subdirectory (e.g. a Go module in ./backend)
+      - type: lsp
+        command: gopls
+        working_dir: ./backend
+
+      # MCP server started from a specific tools directory
+      - type: mcp
+        command: my-mcp-server
+        working_dir: ./tools/mcp

pkg/config/latest/types.go

@@ -741,6 +741,11 @@ type Toolset struct {
 
 	// For the `model_picker` tool
 	Models []string `json:"models,omitempty"`
+
+	// For `mcp` and `lsp` tools - optional working directory override.
+	// When set, the toolset process is started from this directory.
+	// Relative paths are resolved relative to the agent's working directory.
+	WorkingDir string `json:"working_dir,omitempty"`
 }
 
 func (t *Toolset) UnmarshalYAML(unmarshal func(any) error) error {

pkg/config/latest/validate.go

@@ -114,6 +114,9 @@ func (t *Toolset) validate() error {
 	if t.RAGConfig != nil && t.Type != "rag" {
 		return errors.New("rag_config can only be used with type 'rag'")
 	}
+	if t.WorkingDir != "" && t.Type != "mcp" && t.Type != "lsp" {
+		return errors.New("working_dir can only be used with type 'mcp' or 'lsp'")
+	}
 
 	switch t.Type {
 	case "shell":

pkg/config/latest/validate_test.go

@@ -97,6 +97,90 @@ agents:
 `,
 			wantErr: "file_types can only be used with type 'lsp'",
 		},
+		{
+			name: "lsp with working_dir",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: lsp
+        command: gopls
+        working_dir: ./backend
+`,
+			wantErr: "",
+		},
+		{
+			name: "working_dir on non-mcp-lsp toolset is rejected",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: shell
+        working_dir: ./backend
+`,
+			wantErr: "working_dir can only be used with type 'mcp' or 'lsp'",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			var cfg Config
+			err := yaml.Unmarshal([]byte(tt.config), &cfg)
+
+			if tt.wantErr != "" {
+				require.Error(t, err)
+				require.Contains(t, err.Error(), tt.wantErr)
+			} else {
+				require.NoError(t, err)
+			}
+		})
+	}
+}
+
+func TestToolset_Validate_MCP_WorkingDir(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		config    string
+		wantErr   string
+		wantValue string
+	}{
+		{
+			name: "mcp with working_dir",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: mcp
+        command: my-mcp-server
+        working_dir: ./tools/mcp
+`,
+			wantErr:   "",
+			wantValue: "./tools/mcp",
+		},
+		{
+			name: "mcp without working_dir defaults to empty",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: mcp
+        command: my-mcp-server
+`,
+			wantErr:   "",
+			wantValue: "",
+		},
 	}
 
 	for _, tt := range tests {
@@ -111,6 +195,7 @@ agents:
 				require.Contains(t, err.Error(), tt.wantErr)
 			} else {
 				require.NoError(t, err)
+				require.Equal(t, tt.wantValue, cfg.Agents.First().Toolsets[0].WorkingDir)
 			}
 		})
 	}

pkg/config/mcps.go

@@ -86,6 +86,9 @@ func applyMCPDefaults(ts, def *latest.Toolset) {
 	if ts.Defer.IsEmpty() {
 		ts.Defer = def.Defer
 	}
+	if ts.WorkingDir == "" {
+		ts.WorkingDir = def.WorkingDir
+	}
 	if len(def.Env) > 0 {
 		merged := make(map[string]string, len(def.Env)+len(ts.Env))
 		maps.Copy(merged, def.Env)

pkg/config/mcps_test.go

@@ -136,3 +136,25 @@ func TestMCPDefinitions_EnvMerge(t *testing.T) {
 	// Toolset-only key is preserved
 	assert.Equal(t, "from_toolset", ts.Env["EXTRA"])
 }
+
+func TestMCPDefinitions_WorkingDir(t *testing.T) {
+	t.Parallel()
+
+	cfg, err := Load(t.Context(), NewFileSource("testdata/mcp_definitions_working_dir.yaml"))
+	require.NoError(t, err)
+
+	// WorkingDir from the definition is inherited by the referencing toolset.
+	root, ok := cfg.Agents.Lookup("root")
+	require.True(t, ok)
+	require.Len(t, root.Toolsets, 1)
+	ts := root.Toolsets[0]
+	assert.Equal(t, "my-mcp-server", ts.Command)
+	assert.Equal(t, "./tools/mcp", ts.WorkingDir)
+
+	// A toolset-level working_dir overrides the definition's value.
+	override, ok := cfg.Agents.Lookup("override")
+	require.True(t, ok)
+	require.Len(t, override.Toolsets, 1)
+	tsOverride := override.Toolsets[0]
+	assert.Equal(t, "./override/path", tsOverride.WorkingDir)
+}

pkg/config/testdata/mcp_definitions_working_dir.yaml

@@ -0,0 +1,23 @@
+version: "8"
+models:
+  model:
+    provider: openai
+    model: gpt-4o
+
+mcps:
+  custom_mcp_with_dir:
+    command: my-mcp-server
+    working_dir: ./tools/mcp
+
+agents:
+  root:
+    model: model
+    toolsets:
+      - type: mcp
+        ref: custom_mcp_with_dir
+  override:
+    model: model
+    toolsets:
+      - type: mcp
+        ref: custom_mcp_with_dir
+        working_dir: ./override/path

pkg/teamloader/registry.go

@@ -86,6 +86,22 @@ func NewDefaultToolsetRegistry() *ToolsetRegistry {
 	return r
 }
 
+// resolveToolsetWorkingDir returns the effective working directory for a toolset process.
+// If toolsetWorkingDir is set, it is resolved relative to agentWorkingDir (when relative).
+// If toolsetWorkingDir is empty, agentWorkingDir is returned unchanged.
+func resolveToolsetWorkingDir(toolsetWorkingDir, agentWorkingDir string) string {
+	if toolsetWorkingDir == "" {
+		return agentWorkingDir
+	}
+	if filepath.IsAbs(toolsetWorkingDir) {
+		return toolsetWorkingDir
+	}
+	if agentWorkingDir != "" {
+		return filepath.Join(agentWorkingDir, toolsetWorkingDir)
+	}
+	return toolsetWorkingDir
+}
+
 // resolveToolsetPath expands shell patterns (~, env vars) in the given path,
 // then validates it relative to the working directory or parent directory.
 func resolveToolsetPath(toolsetPath, parentDir string, runConfig *config.RuntimeConfig) (string, error) {
@@ -289,7 +305,8 @@ func createMCPTool(ctx context.Context, toolset latest.Toolset, _ string, runCon
 		// Prepend tools bin dir to PATH so child processes can find installed tools
 		env = toolinstall.PrependBinDirToEnv(env)
 
-		return mcp.NewToolsetCommand(toolset.Name, resolvedCommand, toolset.Args, env, runConfig.WorkingDir), nil
+		cwd := resolveToolsetWorkingDir(toolset.WorkingDir, runConfig.WorkingDir)
+		return mcp.NewToolsetCommand(toolset.Name, resolvedCommand, toolset.Args, env, cwd), nil
 
 	// Remote MCP Server
 	case toolset.Remote.URL != "":
@@ -329,7 +346,8 @@ func createLSPTool(ctx context.Context, toolset latest.Toolset, _ string, runCon
 	// Prepend tools bin dir to PATH so child processes can find installed tools
 	env = toolinstall.PrependBinDirToEnv(env)
 
-	tool := builtin.NewLSPTool(resolvedCommand, toolset.Args, env, runConfig.WorkingDir)
+	cwd := resolveToolsetWorkingDir(toolset.WorkingDir, runConfig.WorkingDir)
+	tool := builtin.NewLSPTool(resolvedCommand, toolset.Args, env, cwd)
 	if len(toolset.FileTypes) > 0 {
 		tool.SetFileTypes(toolset.FileTypes)
 	}

pkg/teamloader/registry_test.go

@@ -70,3 +70,59 @@ func TestCreateMCPTool_BareCommandNotFound_CreatesToolsetAnyway(t *testing.T) {
 	require.NotNil(t, tool)
 	assert.Equal(t, "mcp(stdio cmd=some-nonexistent-mcp-binary)", tools.DescribeToolSet(tool))
 }
+
+func TestResolveToolsetWorkingDir(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name              string
+		toolsetWorkingDir string
+		agentWorkingDir   string
+		want              string
+	}{
+		{
+			name:              "empty toolset dir returns agent dir",
+			toolsetWorkingDir: "",
+			agentWorkingDir:   "/workspace",
+			want:              "/workspace",
+		},
+		{
+			name:              "absolute toolset dir is returned as-is",
+			toolsetWorkingDir: "/tmp/mcp",
+			agentWorkingDir:   "/workspace",
+			want:              "/tmp/mcp",
+		},
+		{
+			name:              "relative toolset dir is joined with agent dir",
+			toolsetWorkingDir: "./backend",
+			agentWorkingDir:   "/workspace",
+			want:              "/workspace/backend",
+		},
+		{
+			name:              "relative toolset dir without leading dot is joined with agent dir",
+			toolsetWorkingDir: "tools/mcp",
+			agentWorkingDir:   "/workspace",
+			want:              "/workspace/tools/mcp",
+		},
+		{
+			name:              "relative toolset dir with empty agent dir returns toolset dir unchanged",
+			toolsetWorkingDir: "./backend",
+			agentWorkingDir:   "",
+			want:              "./backend",
+		},
+		{
+			name:              "both empty returns empty",
+			toolsetWorkingDir: "",
+			agentWorkingDir:   "",
+			want:              "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := resolveToolsetWorkingDir(tt.toolsetWorkingDir, tt.agentWorkingDir)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}