mcp-tool-scanner

name	mcp-tool-scanner
description	Scan all installed MCP servers for tool poisoning, unicode hiding, credential exfiltration directives, annotation lying, and rug pulls. Trigger when the user says "scan MCP servers", "audit MCP tools", "check for poisoned servers", "run mcp-sentinel", or any request to check MCP security. Also trigger at session start if no recent scan exists.

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)