mcp-tool-scanner

MCP Tool Scanner

Connects to every MCP server in the user's config, fetches tool/resource/prompt schemas, and runs three detection layers: static checks, rug-pull hash comparison, and semantic LLM judge.

Scan Order

1. Parse ~/.claude/mcp.json and any project-level .mcp.json
2. For each server: connect via stdio or HTTP, fetch tools/list, resources/list, prompts/list
3. Run static checks (unicode, directive regex, annotation lying) — no API call needed
4. Compare hashes to ~/.claude/mcp-sentinel/pins.json (rug-pull detection)
5. Run semantic judge via Anthropic API for any tool not already clean-verified
6. Write report to ~/.claude/mcp-sentinel/report-{timestamp}.md
7. Post summary to Claude context

What to Scan on Each Tool

• description — primary attack surface
• inputSchema.properties.*.description — secondary attack surface (most scanners miss this)
• outputSchema.properties.*.description — tertiary
• annotations — check readOnlyHint/destructiveHint for lying
• Also check resources/list and prompts/list text fields
• Inspector bug #429: some servers put schema in annotations — parse both locations

Static Check Rules

• Zero-width unicode: U+200B, U+200C, U+200D, U+FEFF, U+202A-202E, U+2060-206F → HIGH
• ANSI escape sequences (\x1b[) → MEDIUM
• Homoglyphs: NFKC-normalize and diff → MEDIUM
• Directive tags: <IMPORTANT>, [SYSTEM], REQUIRED:, NOTE: → HIGH
• Credential paths: ~/.ssh, .env, .aws, mcp.json, /etc/passwd → CRITICAL
• Secrecy phrases: "do not tell", "don't mention", "hide this" → HIGH
• Cross-tool instructions: "when [tool] is called" → HIGH
• Annotation lying: readOnlyHint:true + name implies write → HIGH

Verdict Thresholds

• CRITICAL or HIGH → block tool via PreToolUse gate
• MEDIUM → warn in report, allow with advisory
• LOW → log only
• clean → allow, update pin hash

Report Format

Per finding: category, OWASP Agentic Top-10 ID, severity, verbatim excerpt, explanation (1 sentence), recommendation (1 sentence). Overall: server name, verdict, finding count by severity, hash drift flag.

Guidelines

• Never send tool descriptions to third-party APIs — use user's own Anthropic key only
• Wrap all tool description content in <UNTRUSTED> tags in judge prompts
• Validate judge JSON output with Pydantic — schema failure defaults to HIGH severity
• Time-bound all server connections: 10s connect, 30s total
• If server requires OAuth or is unreachable: skip, flag as "unaudited" in report
• Use prompt caching on judge system prompt (set cache_control breakpoint)