#3461 · metadata is not a grant

28 OrchestKit agents declared an MCP server in mcpServers: frontmatter that Claude Code ignores for plugin agents. The real capability grant is the tools: list, and none of them had one, so every declared lookup silently degraded to WebSearch.

declared but could not call

granted read-only after fix

fake tool names corrected

write tools granted

How the silent degrade works

agent run needs library docs | v mcpServers: [context7] <- metadata, Claude Code ignores it | v tools: [Read, Bash, ...] <- the ACTUAL grant, no mcp__context7__* entry | v mcp__context7__query-docs -> NOT AVAILABLE, no error raised | v falls through to WebSearch -> stale or wrong docs, silently

Explore the 28 agents

agent	declares	grant state	tools

Read-only surfaces granted, per server

server	granted (read)	withheld (write / mutating)
context7	resolve-library-id, query-docs	none exist (server is read-only)
tavily	tavily_search, tavily_extract, tavily_crawl, tavily_map, tavily_research	none exist (server is read-only)
memory	search_nodes, read_graph, open_nodes	create_entities, create_relations, add_observations, delete_*

debug-investigator gets the read trio only: a debug run may read the knowledge graph, never mutate it.

Fake tool names (a grant of a nonexistent tool is a no-op)

where	was	now
skills/implement	mcp__context7__query_docs	resolve-library-id + query-docs
skills/fix-issue	mcp__context7__get_library_docs	resolve-library-id + query-docs
agents/web-research-analyst	mcp__memory__add_node	mcp__memory__create_entities
skills/quality-gates (rule)	mcp__memory__add_node	mcp__memory__create_entities

Left alone, on purpose

what	why
7x mcpServers: []	Deliberate "considered MCP, wants none" markers, required by the test-mcp-overhead.sh gate. A prior attempt to delete them was reverted by CI.
stitch, storybook-mcp declarations	Not configured in .mcp.json at all. Granting tools for an unconfigured server achieves nothing; those need a configure-or-drop decision.

The gate that keeps it fixed

tests/agents/test-mcp-declared-vs-granted.sh

(a) every agent declaring a CONFIGURED server in mcpServers:
    must grant at least one matching mcp__<server>__* tool
(b) every mcp__<server>__<tool> token in agents/skills markdown
    must name a tool the server actually exposes

before this PR: 28 (a)-failures + 4 (b)-failures -> exit 1
after this PR:  PASS