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.
This commit is contained in:
2026-11-13 16:06:48 +00:00
parent eeb07e5645
commit b01cfd8eb3
9 changed files with 138 additions and 7 deletions
+5
View File
@@ -59,6 +59,11 @@ blocks; stages communicate through `output.md` (`# handoff`) and `public/`.
`pipelines submit DRAFT` publishes a new immutable version.
`pipelines help <command>` has flags.
Stage `tools` blocks may use `mcp:<server>` or `mcp:<server>/<tool>` 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__<server>__<tool>`).
## References
Read only what the task needs. Rows marked operator only are for setting up or
+10 -1
View File
@@ -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:<server>` / `mcp:<server>/<tool>`, 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__<server>__<tool>`; 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`
@@ -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:<server>` or
`mcp:<server>/<tool>` with names as Claude Code displays them, and prefer
read-only tools.
+4 -3
View File
@@ -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")
}
}
+32 -2
View File
@@ -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...)
}
+24
View File
@@ -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"} },
+8
View File
@@ -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)
+32 -1
View File
@@ -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:<server> or mcp:<server>/<tool> 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
+17
View File
@@ -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"}}