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:
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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...)
|
||||
}
|
||||
|
||||
@@ -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"} },
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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"}}
|
||||
|
||||
Reference in New Issue
Block a user