From b01cfd8eb3306fe338533588a2edf2e7f68640a4 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Fri, 13 Nov 2026 16:06:48 +0000 Subject: [PATCH] Allow named MCP servers in Claude stages Add validated per-stage MCP allowlists while keeping builtin tools separate. Enable matching Claude Code permission rules only for Claude stages, reject unsupported harnesses, and document the unattended-stage safety model. --- internal/author/skill/SKILL.md | 5 +++ internal/author/skill/references/format.md | 11 +++++- internal/author/skill/references/harnesses.md | 6 ++++ internal/pipeline/tools_test.go | 7 ++-- internal/stage/claude_stage.go | 34 +++++++++++++++++-- internal/stage/claude_stage_test.go | 24 +++++++++++++ internal/stage/model.go | 8 +++++ internal/stage/tools.go | 33 +++++++++++++++++- internal/stage/tools_test.go | 17 ++++++++++ 9 files changed, 138 insertions(+), 7 deletions(-) diff --git a/internal/author/skill/SKILL.md b/internal/author/skill/SKILL.md index d8871dc0..9eaf5027 100644 --- a/internal/author/skill/SKILL.md +++ b/internal/author/skill/SKILL.md @@ -59,6 +59,11 @@ blocks; stages communicate through `output.md` (`# handoff`) and `public/`. `pipelines submit DRAFT` publishes a new immutable version. `pipelines help ` has flags. +Stage `tools` blocks may use `mcp:` or `mcp:/` for +Claude-only, allowlisted MCP access. Prefer read-only tools; unattended stages +deny every MCP tool not listed. The name is the Claude Code display name +(mapped internally to `mcp____`). + ## References Read only what the task needs. Rows marked operator only are for setting up or diff --git a/internal/author/skill/references/format.md b/internal/author/skill/references/format.md index c8529af8..47816a11 100644 --- a/internal/author/skill/references/format.md +++ b/internal/author/skill/references/format.md @@ -121,7 +121,8 @@ evidence route to `blocked` when declared, else `error`; never fabricate a resul ## Tools and permissions `tools` lists `read`, `glob`, `grep`, `webfetch`, `websearch`, `edit`, `shell`, -one per line; an empty block denies all and a missing block grants local +or (Claude stages only) `mcp:` / `mcp:/`, one per line; +an empty block denies all and a missing block grants local read/glob/grep/edit/shell (prefer explicit). Roles: `plan` reads (web only when external knowledge is needed); `implement` reads, edits and runs shell; `review` reads and may use shell for `git diff`, never edits; `land` has read/glob/grep and @@ -134,6 +135,14 @@ enables a missing one. Empty arrays deny; wildcards, chaining, redirects and traversal are rejected. With restricted edits and shell enabled, list shell too: `{"edit":["README.md","plugin/*.qml"],"shell":["bash -n install.sh"]}`. +Named MCP entries are an explicit allowlist for unattended Claude stages: +`mcp:ai-memory` allows that server's tools, while `mcp:linear/list_issues` +allows one tool. Names are the server/tool names Claude Code displays (mapped +internally to `mcp____`; claude.ai connectors may look like +`claude_ai_Linear`). Other harnesses reject these entries. Prefer read-only +MCP tools; server configuration is not inspected during validation, so an +unknown name may fail at runtime. + ## Checks Every model stage that can modify the workspace (`edit` or `shell`, no `tools` diff --git a/internal/author/skill/references/harnesses.md b/internal/author/skill/references/harnesses.md index 55713f11..d88c4864 100644 --- a/internal/author/skill/references/harnesses.md +++ b/internal/author/skill/references/harnesses.md @@ -44,3 +44,9 @@ OS sandbox: approved shell can have broad side effects. Usage accumulates across attempts and visits; missing required accounting fails closed. Session/RPC audit lives in the execution user's cache under `pipelines/pi-sessions`; unconfirmed cleanup blocks continuation and retry. + +Claude stages may additionally allow named MCP servers/tools in the `tools` +block. These are Claude-only, exact allowlist entries; other MCP tools remain +denied in unattended `dontAsk` sessions. Use `mcp:` or +`mcp:/` with names as Claude Code displays them, and prefer +read-only tools. diff --git a/internal/pipeline/tools_test.go b/internal/pipeline/tools_test.go index 0952dcdb..c8afd249 100644 --- a/internal/pipeline/tools_test.go +++ b/internal/pipeline/tools_test.go @@ -9,7 +9,8 @@ import ( ) func TestToolsBlockPersistenceAndAdapter(t *testing.T) { - source := strings.Replace(Template([]string{"one"}, true), "```tools\n```", "```tools\nwebsearch\nwebfetch\n```", 1) + source := strings.Replace(Template([]string{"one"}, true), "```tools\n```", "```tools\nmcp:ai-memory\nmcp:linear/list_issues\n```", 1) + source = strings.Replace(source, "provider=opencode-go", "provider=anthropic\nharness=claude", 1) store, err := Open(filepath.Join(t.TempDir(), "tools.db")) if err != nil { t.Fatal(err) @@ -25,10 +26,10 @@ func TestToolsBlockPersistenceAndAdapter(t *testing.T) { t.Fatal(err) } tools, explicit, err := stage.ToolNames(StageDefinition(d.Graph.Stages[0])) - if err != nil || !explicit || len(tools) != 2 || tools[0] != "websearch" { + if err != nil || !explicit || len(tools) != 2 || tools[0] != "mcp:ai-memory" || tools[1] != "mcp:linear/list_issues" { t.Fatal("tool allowlist lost", tools, explicit, err) } - if _, err := Parse(strings.Replace(source, "websearch\nwebfetch", "websearch\nunknown", 1)); err == nil { + if _, err := Parse(strings.Replace(source, "mcp:ai-memory\nmcp:linear/list_issues", "mcp:bad name", 1)); err == nil { t.Fatal("unknown tool accepted") } } diff --git a/internal/stage/claude_stage.go b/internal/stage/claude_stage.go index aed3923f..d4763985 100644 --- a/internal/stage/claude_stage.go +++ b/internal/stage/claude_stage.go @@ -88,12 +88,36 @@ func claudeTools(tools []string) ([]string, error) { case "websearch": names = append(names, "WebSearch") default: + if _, _, ok, err := MCPToolName(tool); err != nil { + return nil, err + } else if ok { + continue + } return nil, fmt.Errorf("Claude Code has no audited builtin for %s; choose read/glob/grep/edit/shell/webfetch/websearch", tool) } } return names, nil } +func claudeMCPAllowRules(tools []string) ([]string, error) { + var rules []string + for _, name := range tools { + server, tool, ok, err := MCPToolName(name) + if err != nil { + return nil, err + } + if !ok { + continue + } + rule := "mcp__" + server + "__*" + if tool != "" { + rule = "mcp__" + server + "__" + tool + } + rules = append(rules, rule) + } + return rules, nil +} + // claudeAllowRules are the pre-approved permission rules. File edits are // approved only below the run directory and the stage's artifacts directory; // everything else a declared tool does not need approval for stays denied by @@ -126,10 +150,16 @@ func (c *ClaudeStageClient) args(config ModelConfig, tools []string, effort stri "--model", config.Model, "--permission-mode", "dontAsk", "--setting-sources", "", - "--strict-mcp-config", "--disable-slash-commands", "--tools", strings.Join(tools, ",")} - if rules := claudeAllowRules(tools, c.Directory, c.ArtifactsDir); len(rules) > 0 { + mcpRules, _ := claudeMCPAllowRules(c.Tools) + if len(mcpRules) == 0 { + tail := append([]string(nil), args[10:]...) + args = append(append(append([]string(nil), args[:10]...), "--strict-mcp-config"), tail...) + } + rules := claudeAllowRules(tools, c.Directory, c.ArtifactsDir) + rules = append(rules, mcpRules...) + if len(rules) > 0 { args = append(args, "--allowedTools") args = append(args, rules...) } diff --git a/internal/stage/claude_stage_test.go b/internal/stage/claude_stage_test.go index a75af454..cefad3be 100644 --- a/internal/stage/claude_stage_test.go +++ b/internal/stage/claude_stage_test.go @@ -217,6 +217,30 @@ func TestClaudeStageDeclaredToolsAreTheOnlyTools(t *testing.T) { } } +func TestClaudeStageNamedMCPToolsAreAllowlistedSeparately(t *testing.T) { + client, root, _ := fakeClaudeClient(t, "success") + client.Tools = []string{"read", "mcp:ai-memory", "mcp:linear/list_issues"} + if _, err := client.Generate(context.Background(), claudeConfig(nil), "task"); err != nil { + t.Fatal(err) + } + calls := fakeClaudeArgs(t, root) + if len(calls) != 1 { + t.Fatal(calls) + } + args := calls[0] + if slices.Contains(args, "--strict-mcp-config") { + t.Fatal("MCP-enabled stage must not use strict MCP config") + } + for _, want := range []string{"--tools", "Read", "--allowedTools", "Read", "mcp__ai-memory__*", "mcp__linear__list_issues"} { + if !slices.Contains(args, want) { + t.Fatalf("missing %q in args %q", want, args) + } + } + if slices.Contains(args, "mcp:ai-memory") || slices.Contains(args, "mcp:linear/list_issues") { + t.Fatalf("MCP entries leaked into builtin tools: %q", args) + } +} + func TestClaudeStageRefusesWhatItCannotEnforce(t *testing.T) { for name, change := range map[string]func(*ClaudeStageClient, *ModelConfig){ "write paths": func(c *ClaudeStageClient, _ *ModelConfig) { c.WritePaths = []string{"app"} }, diff --git a/internal/stage/model.go b/internal/stage/model.go index e4e17340..28bb6790 100644 --- a/internal/stage/model.go +++ b/internal/stage/model.go @@ -118,6 +118,14 @@ func (ModelStage) Spec(def Definition) (ModelSpec, error) { return ModelSpec{}, err } } + if backend != ClaudeBackend { + tools, _, _ := ToolNames(def) + if mcp, err := MCPTools(tools); err != nil { + return ModelSpec{}, err + } else if len(mcp) > 0 { + return ModelSpec{}, fmt.Errorf("named MCP tools are supported only by the claude harness; remove mcp: entries or set harness=claude") + } + } if backend == ClaudeBackend { if def.Configs["provider"] != ClaudeProvider { return ModelSpec{}, fmt.Errorf("the claude harness needs provider=%s", ClaudeProvider) diff --git a/internal/stage/tools.go b/internal/stage/tools.go index b29d25db..fa518497 100644 --- a/internal/stage/tools.go +++ b/internal/stage/tools.go @@ -148,7 +148,11 @@ func ToolNames(def Definition) ([]string, bool, error) { switch name { case "websearch", "webfetch", "read", "glob", "grep", "edit", "shell": default: - return nil, true, fmt.Errorf("unsupported tool %q", name) + if _, _, ok, err := MCPToolName(name); err != nil { + return nil, true, err + } else if !ok { + return nil, true, fmt.Errorf("unsupported tool %q", name) + } } if seen[name] { return nil, true, fmt.Errorf("duplicate tool %s", name) @@ -165,6 +169,33 @@ func ToolNames(def Definition) ([]string, bool, error) { // text-only stage. var legacyTools = []string{"read", "glob", "grep", "edit", "shell"} +var mcpToolName = regexp.MustCompile(`^mcp:([A-Za-z0-9_-]+)(?:/([A-Za-z0-9_-]+))?$`) + +// MCPToolName validates and splits a named MCP allowlist entry. +func MCPToolName(name string) (server, tool string, ok bool, err error) { + if !strings.HasPrefix(name, "mcp:") { + return "", "", false, nil + } + match := mcpToolName.FindStringSubmatch(name) + if match == nil { + return "", "", true, fmt.Errorf("invalid MCP tool %q; use mcp: or mcp:/ with letters, digits, _ or -", name) + } + return match[1], match[2], true, nil +} + +// MCPTools returns named MCP entries in declaration order. +func MCPTools(tools []string) ([]string, error) { + var result []string + for _, name := range tools { + if _, _, ok, err := MCPToolName(name); err != nil { + return nil, err + } else if ok { + result = append(result, name) + } + } + return result, nil +} + // effectiveTools is the single materialisation point for the tools a model // stage is permitted. A present tools block (including an explicit empty block) // is returned exactly as parsed by ToolNames; an absent block yields the legacy diff --git a/internal/stage/tools_test.go b/internal/stage/tools_test.go index 4c4256bf..210af862 100644 --- a/internal/stage/tools_test.go +++ b/internal/stage/tools_test.go @@ -26,6 +26,23 @@ func TestToolsValidation(t *testing.T) { } } +func TestNamedMCPToolsValidation(t *testing.T) { + for _, name := range []string{"mcp:", "mcp:/tool", "mcp:server/", "mcp:server/tool/extra", "mcp:server tool"} { + if _, _, _, err := MCPToolName(name); err == nil { + t.Fatalf("accepted malformed MCP tool %q", name) + } + } + def := Definition{Type: ModelType, Blocks: map[string]string{ + "prompt": "task", "configs": "provider=opencode-go\nmodel=model", + }, Configs: map[string]string{ + "provider": "opencode-go", "model": "model", + }} + def.Blocks["tools"] = "mcp:linear/list_issues" + if err := (ModelStage{}).Validate(def); err == nil || !strings.Contains(err.Error(), "only by the claude harness") { + t.Fatalf("non-Claude MCP stage error = %v", err) + } +} + func TestModelStageBindsExplicitToolPolicyToAgentSession(t *testing.T) { for _, tools := range []string{"websearch\nwebfetch", ""} { client := &AgentClient{Tools: []string{"read", "edit", "shell"}, WritePaths: []string{"one.go"}}