MCP Config Reviewer

MCP configuration and implementation review

Review MCP setups as a security-first configuration audit.

Prefer concrete evidence from the provided config, code, logs, docs, or diff. Do not give generic MCP advice until you have extracted the exact launch command, transport, auth model, tool surface, and trust boundaries.

For Codex or Claude Desktop stdio startup failures such as timed out after X seconds, handshaking with MCP server failed, or connection closed: initialize response, first read references/windows-codex-stdio-debugging.md and follow that flow before recommending larger timeout values.

Review goals

1. Identify whether the request is about configuration only, implementation code, or both.
2. Extract the actual MCP shape:
   • server name and purpose
   • transport (stdio, streamable HTTP, SSE, websocket if present)
   • launch command or container image
   • environment variables and secret sources
   • auth flow and token path
   • exposed tools/resources/prompts
   • filesystem, shell, browser, network, or database reach
3. Report findings by severity with precise remediation.
4. End with a clear ship decision: approve, approve with fixes, or block.

What to inspect first

When the user gives config files such as mcp.json, desktop settings, project config, docker compose, shell launchers, or PR diffs, extract these items before judging quality:

• exact command being executed (npx, node, uvx, python, docker, local binary)
• pinned version vs floating latest tag
• who supplies secrets and where they are stored
• whether tools execute code, shell commands, SQL, filesystem writes, web fetches, or browser actions
• whether the server can reach internal systems or production data
• whether auth uses bearer tokens, API keys, OAuth, sessions, or no auth
• whether logs or traces may capture secrets or prompt content

If details are missing, state the missing evidence explicitly in the report and downgrade confidence.

High-risk findings to look for

Treat these as default high-priority checks.

1. Dangerous server startup and supply-chain risk

Flag when you find:

• npx / pnpm dlx / bunx without a pinned version
• docker images using floating tags like latest
• curl-pipe-shell installers in setup docs
• unreviewed third-party MCP servers with broad host permissions
• startup commands that inherit the full environment by default

Recommended fix pattern:

• pin package or image versions
• prefer reviewed local wrappers over raw remote installers
• pass a minimal explicit environment allowlist
• document expected binary hash or package source when possible

2. Secret handling failures

Flag when you find:

• API keys or tokens hardcoded in config
• secrets committed in .json, .env, shell scripts, or screenshots
• secrets forwarded into subprocesses without need
• verbose logging of auth headers, prompts, or tool arguments containing secrets

Recommended fix pattern:

• move secrets to environment or secret manager
• redact auth material in logs
• scope tokens per server and per environment
• avoid sharing one broad token across multiple MCP servers

3. Over-broad tool exposure

Flag when you find:

• shell execution tools with unrestricted arguments
• filesystem tools rooted at /, home directory, or repository parent
• SQL tools against production without read-only boundaries
• browser or HTTP tools that can hit arbitrary internal hosts
• mixed-purpose servers exposing many unrelated dangerous tools

Recommended fix pattern:

• restrict roots, hosts, schemas, and allowed commands
• split dangerous tools into separate reviewed servers
• add explicit deny rules for destructive operations
• prefer read-only defaults

4. OAuth and token handling problems for MCP

For HTTP-based MCP authorization reviews, check against current MCP authorization requirements:

• clients should use OAuth 2.1 patterns with PKCE
• clients must use the resource parameter for the intended MCP server
• MCP servers must validate that tokens were issued for them
• tokens must not be forwarded to another server that is not their intended audience
• HTTPS is required for authorization endpoints and non-localhost redirects

Block on:

• accepting tokens without audience validation
• forwarding user access tokens from one service to another MCP server
• missing PKCE in authorization code flows
• query-string access tokens
• session-cookie auth used as the primary control for MCP API operations without documented justification

Use references/mcp-review-checklist.md for the security checklist and references/report-template.md for the response shape.

Review workflow

Step 1: inventory the trust boundary

Write one short paragraph covering:

• who launches the MCP server
• what the server can reach
• what credentials it receives
• what destructive actions it can take

Step 2: classify the server

Choose one or more labels:

• local productivity
• developer tooling
• data access
• browser automation
• deployment / infra
• custom business api
• high-risk executor

Use stricter standards as the server gets closer to production systems, shell access, or write actions.

Step 3: run the checklist

Walk the relevant sections from references/mcp-review-checklist.md:

• startup and packaging
• secrets and environment
• authn/authz
• tool capability limits
• network and data egress
• logging and observability
• operational hygiene

For Windows stdio MCP incidents on Codex, also run the targeted startup triage in references/windows-codex-stdio-debugging.md. Treat timeout as a symptom, not a root cause, until you have evidence that the server actually received and failed to answer initialize.

Step 4: produce findings

For every material issue, include:

• severity: critical, high, medium, or low
• evidence: file, key, command, or code path
• why it matters in this topology
• exact remediation

Do not inflate severity for style issues. Do escalate if the server has shell execution, production credentials, or cross-system token forwarding.

Step 5: issue a decision

Use:

• approve when no material risk remains
• approve with fixes when issues are bounded and non-blocking
• block when exploitation could lead to credential theft, arbitrary execution, broad data access, or confused-deputy auth problems

Output format

Follow references/report-template.md.

Default structure:

1. summary
2. architecture snapshot
3. findings
4. missing evidence
5. decision

Keep the summary short. Spend most space on evidence-backed findings.

Review heuristics

• Prefer least privilege over convenience.
• Prefer pinned dependencies over dynamic download at runtime.
• Prefer server-specific credentials over shared global credentials.
• Prefer read-only and narrow roots over broad access.
• Prefer explicit allowlists over open-ended tool inputs.
• Prefer separate MCP servers for unrelated trust domains.
• If a tool can execute code, write files, access private networks, or mutate production state, assume abuse paths exist until constrained.
• Prefer proving where stdio failed over increasing startup_timeout_sec blindly.
• For Windows stdio MCP servers, test whether the client is sending newline-delimited JSON or Content-Length framed messages; do not assume one format.

What good looks like

A strong MCP setup usually has:

• pinned package or image versions
• a minimal environment allowlist
• narrowly scoped filesystem or network permissions
• read-only defaults where possible
• clear OAuth audience/resource handling for HTTP transports
• no hardcoded secrets
• concise operational docs describing upgrade, rollback, and owner

Do not do this

• Do not approve a config just because it “works locally”.
• Do not assume stdio is safe by default; review the launched command and inherited environment.
• Do not assume OAuth is correct because a login screen exists.
• Do not bury the blocking issue under many minor suggestions.
• Do not recommend adding broader permissions to “fix” broken tools without calling out the security tradeoff.