Merge pull request #2460 from simonferquel-clanker/feat/toolset-working-dir

feat: add optional working_dir to MCP and LSP toolset configs

Author: simonferquel

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. Only valid for subprocess-based MCP types (command or ref); not supported for remote MCP toolsets."
         }
       },
       "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', and not supported for remote MCP toolsets (no local subprocess)."
         }
       },
       "additionalProperties": false,

docs/configuration/tools/index.md

@@ -65,6 +65,7 @@ Browse available tools at the [Docker MCP Catalog](https://hub.docker.com/search
 | `tools`       | array  | Optional: only expose these tools                                |
 | `instruction` | string | Custom instructions injected into the agent's context            |
 | `config`      | any    | MCP server-specific configuration (passed during initialization) |
+| `working_dir` | string | Working directory for the MCP gateway subprocess. Only applies when the catalog entry runs as a local process (not remote). Relative paths are resolved against the agent's working directory. |
 
 ### Local MCP (stdio)
 
@@ -86,6 +87,7 @@ toolsets:
 | `args` | array | Command arguments |
 | `tools` | array | Optional: only expose these tools |
 | `env` | object | Environment variables (key-value pairs) |
+| `working_dir` | string | Working directory for the MCP server process. Relative paths are resolved against the agent's working directory. Defaults to the agent's working directory when omitted. |
 | `instruction` | string | Custom instructions injected into the agent's context |
 | `version` | string | Package reference for [auto-installing](#auto-installing-tools) the command binary |
 

docs/tools/lsp/index.md

@@ -65,6 +65,7 @@ agents:
 | `args` | array | ✗ | Command-line arguments for the LSP server |
 | `env` | object | ✗ | Environment variables for the LSP process |
 | `file_types` | array | ✗ | File extensions this LSP handles (e.g., `[".go", ".mod"]`) |
+| `working_dir` | string | ✗ | Working directory for the LSP server process. Relative paths are resolved against the agent's working directory. Defaults to the agent's working directory when omitted. |
 | `version` | string | ✗ | Package reference for [auto-installing]({{ '/configuration/tools/#auto-installing-tools' | relative_url }}) the command binary |
 
 ## Common LSP Servers
@@ -81,6 +82,16 @@ toolsets:
     file_types: [".go"]
 ```
 
+If your Go module lives in a subdirectory (e.g. a monorepo where `go.mod` is under `./backend`), set `working_dir` so `gopls` is started from the module root:
+
+```yaml
+toolsets:
+  - type: lsp
+    command: gopls
+    file_types: [".go"]
+    working_dir: ./backend  # gopls must be started from the module root
+```
+
 ### TypeScript/JavaScript (typescript-language-server)
 
 ```yaml

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-5-mini
+    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,13 @@ 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'")
+	}
+	// working_dir requires a local subprocess; it is meaningless for remote MCP toolsets.
+	if t.WorkingDir != "" && t.Type == "mcp" && t.Remote.URL != "" {
+		return errors.New("working_dir is not valid for remote MCP toolsets (no local subprocess)")
+	}
 
 	switch t.Type {
 	case "shell":

pkg/config/latest/validate_test.go

@@ -97,6 +97,106 @@ 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: "",
+		},
+		{
+			name: "working_dir on remote mcp is rejected",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: mcp
+        remote:
+          url: https://mcp.example.com/sse
+        working_dir: ./tools
+`,
+			wantErr:   "working_dir is not valid for remote MCP toolsets",
+			wantValue: "",
+		},
 	}
 
 	for _, tt := range tests {
@@ -111,6 +211,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,13 @@ func applyMCPDefaults(ts, def *latest.Toolset) {
 	if ts.Defer.IsEmpty() {
 		ts.Defer = def.Defer
 	}
+	if ts.WorkingDir == "" {
+		// An empty working_dir in the referencing toolset is treated as "unset":
+		// inherit the definition's value. This matches the semantics of all other
+		// string fields in this function. An explicit `working_dir: ""` in YAML
+		// is indistinguishable from omission and will therefore be overridden.
+		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