feat(mcp): declare MCP servers in a skill, gated like the code they are

[singhharsh1708]

What

A skill can now declare the MCP servers it needs in [mcp.servers.<name>]. compile writes the native config for every target that has one, and the install gate reviews it first.

[mcp.servers.deploy-tools]
transport = "stdio"                        # stdio | streamable-http | sse
command = "npx"                            # a single executable, never a shell string
args = ["-y", "@acme/deploy-mcp@2.4.1"]    # pin it — unpinned fails the gate
tools = ["plan_diff"]                      # required: deny-by-default allowlist

[mcp.servers.deploy-tools.env]
DEPLOY_TOKEN = "${ACME_DEPLOY_TOKEN}"      # a reference; a literal credential fails the gate

Only three targets emit anything — deliberately

Of the eleven targets, only three have a dedicated, project-scoped, primary-source-confirmed MCP config file:

Target	File
claude-code	.mcp.json
copilot	.github/mcp.json
agent-plugins	<plugin-root>/mcp.json

The rest have no MCP mechanism (aider, agentsmd), no project scope (cline, windsurf are user-global only), or keep servers in a shared settings file alongside unrelated user config (zed, gemini) — and Cursor's file cannot express a tools allowlist, so a declaration there would be silently widened. Emitting a plausible-looking file for any of those produces something that reads as configured and does nothing, which is the failure this project exists to prevent. They get a typed warning naming the reason (no-mcp-surface, no-project-scope, needs-shared-file-merge) and no file.

Nothing is passed through

The client dialects genuinely disagree, so every emitter translates:

• streamable-http → http for Claude Code and Copilot, left as-is for Agent Plugins
• An explicit type is always written — a url with no type is a documented hard error in Claude Code
• tools is written only where the format has a field, with a warning where it doesn't — never a silent drop
• Agent Plugins' mcp.json gets exactly its two allowed top-level keys and the byte-exact $schema const

Trust

MCP lints join the four safety lints as non-bypassable — a server declaration is a request to run third-party code with your agent's permissions. Blocked with --yes: shell strings and shell metacharacters, unpinned versions (@latest, ^, >=), plain http off loopback, credentials in a URL, missing tools, malformed/duplicate names, and literal credentials in env/headers.

Secrets may only appear as ${VAR}. Where a format defines no credential reference and expands no variables (Agent Plugins), the server is omitted with a warning rather than emitted with a reference that would never resolve.

Notes

• The manifest uses ${VAR} references rather than an inline-table { secret = "NAME" } form: this repo's TOML parser has no inline-table support, and extending it was more risk than the syntax was worth.
• I verified the claim that our agent-plugin/ layout was wrong — it isn't. plugin.json and skills/ are already siblings at the plugin root, as the spec requires, so mcp.json joins them there.

28 new tests. Full suite, typecheck, site --check, bench gate and self-lint all green. Ships as 0.19.0.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
kitbash	Ready	Preview	Aug 9, 2026 7:54pm