MCP security review: static checks before merge

Problem

The Model Context Protocol made agent capability pluggable. That is the point — and the risk. A one-line edit to .mcp.json adds a server with every tool it exposes; a wildcard entry in a tool allowlist exposes tools nobody enumerated; an approval mode flipped to approve removes the human from a side-effecting call. None of this looks like application code in review, and much of it is written by coding agents themselves. Line-by-line diff review was never designed to answer the question these changes raise: what can the agent do now that it could not do before?

Two distinct MCP surfaces need review. The first is your agent product's tool surface — the servers and tools your agent calls at runtime, declared as MCP exports in shipgate.yaml. The second is the coding-agent host's own grants — which MCP servers Claude Code, Cursor, or Codex trusts in your repo, plus permission rules and hooks. A PR can widen either one silently.

What a static MCP security review covers

Tool inventories from MCP exports. Each tool is named, schema-checked, and risk-tagged from a committed tool source snapshot, so the reviewed surface is the released surface — the defense against tool surface drift.
Wildcard tool surfaces. SHIP-INVENTORY-WILDCARD-TOOLS fires when a source declares all-tools or wildcard exposure, and SHIP-MCP-UNKNOWN-TOOL-SCHEMA fires when a tool's side effect cannot be proven from its static schema.
Scope and approval coverage. SHIP-MCP-AUTO-APPROVE-SIDE-EFFECT (critical) fires when a write, destructive, external, financial, or production tool is auto-approved, and SHIP-MCP-PERMISSION-EXPANDED flags a PR that broadens an MCP capability's scope, effect, or controls versus base.
Secret passthrough. SHIP-MCP-ENV-SECRET-PASSTHROUGH flags servers that declare secret-like env vars or pass through secret-like host env references. Key names appear in the evidence; values are never copied.
Host-level MCP grants. Each host surface has its own checks. MCP server declarations — a changed .mcp.json, .cursor/mcp.json, or .vscode/mcp.json — raise SHIP-HOST-BOUNDARY-MCP-SERVER-ADDED or SHIP-HOST-BOUNDARY-MCP-SERVER-CHANGED. Claude Code settings (.claude/settings.json permission rules and hooks) get the permission and hook checks: a wildcard allow rule like Bash(*) raises the blocking SHIP-HOST-BOUNDARY-PERMISSION-WILDCARD-ALLOW, with SHIP-HOST-BOUNDARY-PERMISSION-ALLOW-EXPANDED, SHIP-HOST-BOUNDARY-PERMISSION-DENY-REMOVED, and SHIP-HOST-BOUNDARY-HOOK-CHANGED covering allowlist growth, deny-rule removal, and hook edits. Codex repo config (.codex/config.toml, hooks.json) is covered by the SHIP-CODEX-BOUNDARY-* checks — e.g. auto-approval of a write-capable MCP tool raises SHIP-CODEX-BOUNDARY-MCP-AUTO-APPROVE-WRITE. These families are suppression-immune and severity-floor-protected, so an agent cannot pass its own PR by editing the gate.

How to run it

Boundary check in the working tree — coding agents (and the --agent codex / --agent cursor variants) get one stdout JSON verdict:

shipgate check --agent claude-code --workspace . --format codex-boundary-json

Verify a PR's MCP and capability delta against its base, in advisory mode first:

agents-shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --format json

Read agent-handoff.json first (gate.merge_verdict, then controller), then verifier.json as the authoritative controller substrate. The gate itself is report.json → release_decision.decision; the merge verdict is a deterministic projection of it, never a second decision.

Inventory the host's standing MCP grants — including on repos with no shipgate.yaml — then baseline and watch for host-grant drift:

shipgate audit --host --json --out agents-shipgate-reports/host-grants.json
shipgate audit --host --save-baseline
shipgate audit --host --drift --fail-on-drift

Drift exits 20 with --fail-on-drift, and the report names expansion signals: a new server, a new allow rule, a removed deny rule, a new hook, a workflow gaining write scopes. Secret values are redacted before hashing, so rotating a token is not drift — changing what a server can do is.

What it does not do

It is not a runtime gateway. Nothing is intercepted at call time; the review runs at PR time on declared configuration. See Agents Shipgate vs MCP gateways — most teams want both layers.
It does not vet servers. It flags that a server was added and what it can reach; whether the server is trustworthy is a human decision.
It only sees declared and discoverable surfaces. Every check is a static check over committed files and exports. A dynamic surface that cannot be enumerated is flagged as unreviewable, not silently resolved.
It is not a sandbox. Runtime enforcement belongs to the host and the OS.

Agents Shipgate is pre-1.0 beta software. Detection accuracy is still being validated with design partners, and no precision or recall figures are published yet — treat findings as a structured review aid with a deterministic gate, not a guarantee.

FAQ

What does an MCP security review with Agents Shipgate cover?

It statically reviews two surfaces: the agent's MCP tool inventory (exported tool lists, wildcard exposure, auto-approved side-effecting tools, secret env passthrough, per-PR capability expansion) and the coding-agent host's own MCP grants (which servers the host trusts, permission rules, and hooks).

Does Agents Shipgate connect to my MCP servers?

No. It scans exported tool inventories and declared host configuration files. There is no agent execution, no LLM call, no MCP connection, no network access, and no telemetry in the default static path.

Is this a replacement for an MCP gateway?

No. A gateway decides whether a specific tool call may proceed at runtime. Agents Shipgate reviews the MCP surface at PR time, before the release reaches the gateway. Teams that care about MCP security typically want both.

Which files count as host-level MCP grants?

.mcp.json and .claude/settings.json (Claude Code), .cursor/mcp.json (Cursor), .vscode/mcp.json (VS Code), .codex/config.toml and .codex/hooks.json (Codex), and .github/workflows files that set CI permissions.

What happens when a PR adds a new MCP server?

SHIP-HOST-BOUNDARY-MCP-SERVER-ADDED routes the PR to human review, and a wildcard-shaped allow rule such as Bash(*) raises the blocking SHIP-HOST-BOUNDARY-PERMISSION-WILDCARD-ALLOW. These checks are suppression-immune: checks.ignore cannot hide them.

Can Agents Shipgate tell me whether an MCP server is trustworthy?

No. It flags that a server was added or changed and what that server can reach. Whether the server itself is trustworthy — pinning versions, auditing the package, restricting env passthrough — remains a human review decision.

Review MCP servers and permissions before they merge.