mcp-scanner

What this skill does

# MCP Scanner

Evaluate MCP servers for safety, functionality, and legal compliance before installation.

## Communication Style

**Always default to plain language.** The user may not be technical. Use everyday analogies to explain security concepts. Only provide technical details (OWASP codes, code snippets, severity levels) when the user explicitly asks for them.

## Workflow

### Step 1: Understand What the User Wants

Before scanning, ask:
1. "What are you hoping this MCP will do for you?"
2. "Do you have any specific concerns about it?"

This helps you assess whether the MCP actually meets their needs.

### Step 2: Get the URL

Ask the user for the URL to the MCP. Accept:
- GitHub repository URLs
- npm package URLs
- PyPI package URLs
- Direct links to source files

### Step 3: Fetch Source Code

Use WebFetch to retrieve key files. See [url-patterns.md](references/url-patterns.md) for URL conversion patterns.

Fetch in this order:
1. **README.md** - Understand what the MCP claims to do
2. **LICENSE** - Check legal terms
3. **package.json** or **pyproject.toml** - Dependencies and entry point
4. **Main source file** - The actual code (index.ts, server.py, etc.)
5. **Tool definition files** - Where tools are registered

### Step 4: Analyze

#### A. Functionality Check
- Does the MCP do what the user needs?
- What tools/capabilities does it provide?
- Are there limitations or missing features?
- What setup is required?

#### B. Security Analysis
Review against [security-checklist.md](references/security-checklist.md). Look for:
- Critical: Hardcoded secrets, command injection, data exfiltration
- High: Missing auth, overly permissive scopes, token issues
- Medium: Missing logging, error handling
- Low: Missing docs, tests
- MCP-Specific: Tool annotations, transport security, spec compliance

#### C. Legal/License Check
Review against [license-guide.md](references/license-guide.md). Check:
- Is there a license file?
- What type of license?
- Any commercial use restrictions?

#### D. Current Advisories (Optional)
For high-stakes decisions, check [authoritative-sources.md](references/authoritative-sources.md) for:
- Known security advisories from AAIF/Linux Foundation
- Current OWASP MCP Top 10 guidance
- Whether the MCP is in any official registry

### Step 5: Deliver Report

**Always use the Plain Language Report first.**

---

## Report Template (Plain Language - Always Show This)

```
## MCP Assessment: [Name]

### The Bottom Line
[One sentence verdict: Safe to use / Proceed with caution / Don't install this]

### What This Tool Does
[2-3 sentences in plain English. What problem does it solve? How does it work?]

### Will It Work For You?
[Based on what they told you they want]
[Yes / No / Partially] - [Brief explanation]

### Should You Be Concerned?
[Plain language summary. Use analogies from the checklist.]
[If concerns exist, explain in everyday terms]
[If no concerns, say so clearly]

### My Recommendation
[Clear, actionable advice]

---
*Want the technical details? Just ask and I'll provide the full security analysis.*
```

---

## Technical Report (Only When Requested)

If user asks for details, provide:

```
### Detailed Security Findings

| Severity | Finding | Location |
|----------|---------|----------|
| [CRITICAL/HIGH/MEDIUM/LOW] | [Description] | [File:line] |

### OWASP MCP Top 10 Check
- MCP01 Token Mismanagement: [Pass/Fail/N/A]
- MCP02 Privilege Escalation: [Pass/Fail/N/A]
- [Continue for all 10...]

### License Details
- License Type: [Name]
- Commercial Use: [Yes/No/Conditional]
- Modification Allowed: [Yes/No/Conditional]
- Distribution Requirements: [Description]

### Dependencies of Concern
[List any suspicious or outdated dependencies]

### Code Snippets
[Relevant code showing concerns]
```

---

## Verdict Criteria

### Safe to Use
- No critical or high severity findings
- Clear, permissive license (MIT, Apache, BSD)
- Does what user needs
- Active maintenance (recent commits, responses to issues)

### Proceed with Caution
- Has medium severity findings OR
- Copyleft license (GPL, LGPL) OR
- Partially meets user needs OR
- Limited maintenance OR
- Missing documentation

### Don't Install This
- Any critical severity finding OR
- No license file OR
- Evidence of malicious intent OR
- Abandoned with known vulnerabilities OR
- Does not do what user needs

---

## Example Analogies

Use these to explain technical concepts:

| Concept | Analogy |
|---------|---------|
| Hardcoded credentials | "Like writing your PIN on your debit card" |
| Command injection | "Letting someone send commands to your computer through a text field" |
| Data exfiltration | "This tool might be sending your information somewhere without asking" |
| Overly permissive access | "Like giving the plumber keys to your whole house when they only need the bathroom" |
| No license | "The author hasn't said you can use this - legally risky" |
| Missing audit logs | "No record of what this tool does - like a store with no security cameras" |
| Token passthrough | "Like a security guard who waves through anyone with a badge, real or fake" |

---

## What If I Can't Access the Code?

If the repository is private or returns 404:
- Inform the user you cannot access the source code
- Explain that without code review, you cannot verify safety
- Suggest they contact the author or find an alternative with public source code

---

## Staying Current

The MCP ecosystem evolves rapidly. This skill uses foundational security principles that don't change, but specific advisories and best practices do.

**For high-stakes decisions**, use WebFetch to check:
1. `https://modelcontextprotocol.io/specification/draft/basic/security_best_practices` - Latest official guidance
2. `https://owasp.org/www-project-mcp-top-10/` - Current vulnerability categories

**What stays stable** (hardcoded in this skill):
- Core security patterns (injection, exfiltration, auth gaps)
- License compatibility principles
- MCP Trust Principles (consent, control, privacy)
- Tool annotation expectations

**What changes** (check authoritative sources):
- Specific CVEs and advisories
- New attack vectors
- Ecosystem registries and certifications
- Governance updates

See [authoritative-sources.md](references/authoritative-sources.md) for the full list of trusted sources.