feat(agents): explicit MCP-tools listing for vercel-preview-auditor + ci-triage-engineer#228
Merged
Merged
Conversation
… ci-triage-engineer Surfaced by the post-PR-#225 live-fire of the three new sub-agents on 2026-05-23 (session 4). vercel-preview-auditor returned a clean WAIT verdict citing "Vercel MCP not reachable in subagent session" — a real infrastructure gap, not an agent prompt issue. ci-triage-engineer worked around the same gap by falling back to git history + the squash-merge commit body (correct fallback discipline) but hit GitHub API rate-limits on the unauthenticated fallback path. Root cause: the Claude Code sub-agent runtime does NOT auto-inherit MCP tools from the parent session. Each sub-agent is restricted to the tools listed explicitly in its `tools:` frontmatter field; MCP tools must be enumerated by full name `mcp__<server>__<tool>`. Two-part fix: (a) `.claude/agents/vercel-preview-auditor.md` — `tools:` frontmatter extended to list 7 Vercel MCP tools by their UUID-namespaced name (`mcp__0addee55-c9d7-44a2-b1b2-355b2d3fc4fd__*`): list_deployments / get_deployment / get_deployment_build_logs / get_runtime_logs / web_fetch_vercel_url / get_project / list_projects. Hard-constraint bullet added: "If Vercel MCP tools are NOT in your context, surface as WAIT (MCP access gap) and escalate to main; do NOT fabricate deployment status." The UUID is OAuth-connection-specific so a fresh clone by a different user would have a different UUID and the pinned frontmatter would silently fail to match — the escalation path keeps the agent useful in that scenario. (b) `.claude/agents/ci-triage-engineer.md` — `tools:` frontmatter extended to list 6 GitHub MCP tools (stable `mcp__github__*` namespace): pull_request_read / list_pull_requests / list_commits / get_commit / search_pull_requests / search_code. Hard-constraint bullet added: "If GitHub MCP unavailable, may fall back to local git history as primary evidence (squash-merge commit body, refs) — but must explicitly cite the access gap in the report; never fabricate check-run IDs or log URLs." Docs: - CLAUDE.md §Gotchas — new bullet documenting the sub-agent MCP inheritance limitation so future agent authors don't repeat the gap; lists the GitHub stable-namespace vs UUID-based connector distinction - CLAUDE.md §Phase status — in-flight entry for this PR + reworded 2 stale "in flight (this PR)" headers from PR #226 + PR #227 to "merged via PR #N" so the §Phase status tracker reflects post-merge state - AGENTS.md §Phase + version state — mirrored in-flight entry + same PR #227 stale-header reword Doc-only PR — no compute / schema / scoring / valuation / frontend / Python / TS production-code change. Tests unchanged. ruff trivially passes. https://claude.ai/code/session_01JwntEE4PNAXSMkZxRA9BB4
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Surfaced by the post-PR-#225 live-fire of the three new sub-agents on 2026-05-23 (session 4):
vercel-preview-auditorreturned a cleanWAIT (MCP access gap — not a deployment failure)verdict — could not reach Vercel MCP tools at all.ci-triage-engineerworked around the same gap by falling back to git history + the squash-merge commit body (correct fallback discipline) but hit GitHub API rate-limits on the unauthenticated fallback.literature-searcherworked correctly (itstools:already listsWebSearch, WebFetchexplicitly — that's why it worked).Root cause: the Claude Code sub-agent runtime does NOT auto-inherit MCP tools from the parent session. Each sub-agent is restricted to the tools listed in its
tools:frontmatter field; MCP tools must be enumerated by full name (mcp__<server>__<tool>). The original two agents both described themselves as MCP-driven but theirtools:field only listedRead, Bash, Grep, Glob.Two-part fix
(a)
tools:frontmatter extended on both agentsvercel-preview-auditormcp__0addee55-...__*):list_deployments·get_deployment·get_deployment_build_logs·get_runtime_logs·web_fetch_vercel_url·get_project·list_projectsci-triage-engineermcp__github__*):pull_request_read·list_pull_requests·list_commits·get_commit·search_pull_requests·search_code(b) Hard-constraint bullets for MCP-access-gap failure mode
vercel-preview-auditorWAIT (MCP access gap — not a deployment failure)+ escalate to main agent. Do NOT fabricate deployment status. (Vercel UUID is OAuth-connection-specific → a fresh clone by a different user would have a different UUID + this pinned frontmatter would silently fail to match → escalation path keeps agent useful in that scenario.)ci-triage-engineerDocs
CLAUDE.md§Gotchas — new bullet documenting the sub-agent MCP inheritance limitation; calls out the GitHub stable-namespace (mcp__github__*) vs OAuth-UUID-based connector distinction so future agent authors don't repeat the gap.CLAUDE.md§Phase status — new in-flight entry for this PR + reworded 2 stalein flight (this PR)headers from PR docs+agent: post-Dependabot-wave doc fixes (W1 FORM4_FETCH_SKIP + W3 literature-searcher injection guard) #226 (Dependabot triage) + PR test(form4_signals): PR-#224 review-nit polish — 2 of 3 quantrank-reviewer WARNs land #227 (review-nit polish) tomerged via PR #Nfor post-merge accuracy.AGENTS.md§Phase + version state — mirrored in-flight entry + same PR test(form4_signals): PR-#224 review-nit polish — 2 of 3 quantrank-reviewer WARNs land #227 stale-header reword. Cross-tool note that the underlying limitation is Claude-Code-runtime-specific (not relevant to Copilot / Cursor / Devin).Files touched
.claude/agents/vercel-preview-auditor.md.claude/agents/ci-triage-engineer.mdCLAUDE.mdAGENTS.mdDoc-only — no compute / schema / scoring / valuation / frontend / Python / TS production-code change. Tests unchanged.
rufftrivially passes.Test plan
git diff --statconfirms 4 files / +105 −8docs-reviewersubstance check before flipping to ReadyVerification (post-merge follow-up)
A second live-fire of
vercel-preview-auditorafter this merges should confirm:list_deploymentsreturns the actual deployment listIf the UUID
0addee55-c9d7-44a2-b1b2-355b2d3fc4fddoes NOT match this Claude installation's actual Vercel MCP server registration, the new hard-constraint will trigger theWAITescalation — keeping the regression visible.Out of scope (follow-ups)
ghshells)_FOOTNOTES_REQUIRED_ATTRSextension) — still needs@networkverifycompute-rankings.ymlworkflow-perm narrowing) + W4 (log-bash.shscrub) — low-priority deferred security WARNshttps://claude.ai/code/session_01JwntEE4PNAXSMkZxRA9BB4
Generated by Claude Code