references/mcp_and_plugin_governance.md
MCP servers, plugins and marketplaces
Every MCP server is code that runs with an engineer's credentials, and every
plugin can bring hooks, agents and its own MCP servers. This is what
mcp_plugin_inventory.py reads and why each check exists.
Confidence key: 🟢 verified on code.claude.com/docs or the cited source · 🔴 recommendation.
1. Where MCP servers come from
| Scope | Location | Committed? |
|---|---|---|
| Local (default for claude mcp add) | ~/.claude.json → projects["<path>"].mcpServers | no |
| Project | .mcp.json at the repo root, key mcpServers | yes |
| User | ~/.claude.json → mcpServers | no |
| Managed | managedMcpServers, or managed-mcp.json beside managed-settings.json | IT |
Precedence: managed > local > project > user > plugin > claude.ai connectors;
same-name entries are not merged. 🟢 [mcp] .mcp.json expands ${VAR} and
${VAR:-default}, so a committed file never needs a literal secret. 🟢 [mcp]
managed-mcp.json takes exclusive control; {"mcpServers": {}} disables MCP. 🟢 [managed-mcp]
2. Approval
- Project servers need approval.
enabledMcpjsonServers/disabledMcpjsonServersapprove by name;enableAllProjectMcpServers: trueapproves everything in.mcp.json, including the server a teammate adds next week. A committedenable*value is ignored in an untrusted folder. 🟢 [settings-reference] allowedMcpServers/deniedMcpServersentries take exactly one ofserverUrl(supports*),serverCommand(exact array) orserverName(exact; the docs note a name alone is not a security control). Unset allowlist = everything allowed;[]= nothing. Deny always wins and merges from every scope; allowlists also merge unlessallowManagedMcpServersOnly: true. 🟢 [managed-mcp]
Recommendation: approve by serverUrl or serverCommand in managed
settings, and keep the human-readable allowlist file (approved-components.json)
for the inventory diff. 🔴
3. Pinning
An npx -y some-mcp-server entry runs whatever version the registry serves
that day. OWASP lists supply-chain compromise and excessive agency among the
top risks for LLM applications; an unpinned server with broad tool access is
both. 🟢 [OWASP] Pin the package ([email protected], pkg==0.6.2) and update it on
purpose. 🔴
4. Plugins and marketplaces
enabledPluginsmaps"name@marketplace"to a boolean; a managedfalseblocks the plugin everywhere. 🟢 [settings-reference]extraKnownMarketplaces(aliasadditionalMarketplaces) registers sources; from a repo file it applies only after trust. 🟢 [settings-reference]strictKnownMarketplaces(managed) is the source allowlist;[]blocks every marketplace, the official one included.blockedMarketplaces(managed) takes the same source objects, including"owner/*". 🟢 [settings-reference]strictPluginOnlyCustomizationlocks skills, agents, hooks and/or MCP to plugin and managed sources, so customization ships only through reviewed plugins. 🟢 [managed-settings]
Pin a git or GitHub marketplace with ref so its contents cannot change between
review and install. 🔴
5. Review checklist for a new server or plugin
- Who maintains it, and is the source readable? (Open source or internal.)
- What credentials does it receive? Scope them to read-only where possible.
- Which tools does it expose? Deny the destructive ones with
mcp__server__toolrules. - Is it pinned?
- Does it send data off the machine, and is that allowed by your data policy?
- Who owns it on your side, and when is it re-reviewed?
A plugin or server that fails 5 is a data-protection question before it is an engineering one. 🔴
Sources
- Claude Code docs — MCP. https://code.claude.com/docs/en/mcp
- Claude Code docs — Managed MCP. https://code.claude.com/docs/en/managed-mcp
- Claude Code docs — Settings reference. https://code.claude.com/docs/en/settings-reference
- Claude Code docs — Managed settings. https://code.claude.com/docs/en/managed-settings
- Claude Code docs — Permissions (MCP rule forms). https://code.claude.com/docs/en/permissions
- OWASP Top 10 for LLM Applications. https://genai.owasp.org/llm-top-10/