MCP Hub Security

Security gate for MCP servers and Claude Code Skills.
Scan any Git repository or SKILL.md against 14+ vulnerability classes before trusting it.

Version Python License MCP Hub

Quick install · Claude Code setup · How it works · Tools reference · Get API key

Table of Contents

• What is this?
• Features
• Quick install
• MCP client configuration — includes watchdog setup for Claude Code
• How it works
• Environment variables
• Available tools
• Examples
• Troubleshooting

What is this?

MCP Hub Security is an MCP server that acts as a security gate for your AI agent workflows. Before your agent runs an MCP server from a Git repository — or loads a Claude Code Skill — it can call this server to get a full vulnerability analysis from mcp-hub.info.

It detects 14 vulnerability classes including:

• Prompt injection & instruction override
• Secret and credential exposure
• Tool poisoning & shadow tools
• SSRF and unsafe network calls
• Dangerous capabilities (exec, file write, env access)
• Data exfiltration vectors
• ...and more mapped to the OWASP MCP Top 10

Skills support: Claude Code Skills (SKILL.md files) are scanned by 17 dedicated analyzers covering 61 rules — detecting instruction overrides, capability abuse, prompt injection hooks, and more.

Features

• MCP server scanning — submit any GitHub, GitLab, or Bitbucket repository and get a security score (0–100), risk level, capabilities list, OWASP coverage, and full findings.
• Skill scanning — scan a SKILL.md by content or URL; get a pass/fail verdict under configurable policy.
• Policy engine — configure minimum score, maximum risk level, and denied capabilities via environment variables. The server enforces policy and returns allowed: true/false with clear reasons.
• Proactive watchdog hook — a Claude Code PostToolUse hook that automatically scans any SKILL.md you create or edit and warns you immediately.
• Credit-aware — each scan costs 5 credits; cached results (same commit SHA) are free. Balance is always returned.
• Zero install steps — uvx fetches and runs the server on first use; no virtualenv to manage. The server itself talks to the API with the Python stdlib (no httpx/requests); the only runtime dependency is fastmcp.

Quick install

No installation needed. All configs below use uvx — it fetches and runs the server automatically on first use.

The only thing you need: an API key → mcp-hub.info/accounts/dashboard/ → API Tokens tab.

MCP client configuration

Before you start: get your API key at mcp-hub.info/accounts/dashboard/ → API Tokens. You will need to replace YOUR_API_KEY in the configs below — that is the only thing you need to change.

{
  "mcpServers": {
    "mcp-hub-security": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/mcp-hub-corp/[email protected]", "mcp-hub-security"],
      "env": {
        "MCPHUB_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "uvx --from git+https://github.com/mcp-hub-corp/[email protected] mcp-hub-skill-watchdog",
            "env": {
              "MCPHUB_API_KEY": "YOUR_API_KEY"
            }
          }
        ]
      }
    ]
  }
}

{
  "mcpServers": {
    "mcp-hub-security": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/mcp-hub-corp/[email protected]", "mcp-hub-security"],
      "env": {
        "MCPHUB_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

{
  "servers": {
    "mcp-hub-security": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/mcp-hub-corp/[email protected]", "mcp-hub-security"],
      "env": {
        "MCPHUB_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-hub-security": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/mcp-hub-corp/[email protected]", "mcp-hub-security"],
      "env": {
        "MCPHUB_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-hub-security": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/mcp-hub-corp/[email protected]", "mcp-hub-security"],
      "env": {
        "MCPHUB_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

{
  "context_servers": {
    "mcp-hub-security": {
      "command": {
        "path": "uvx",
        "args": ["--from", "git+https://github.com/mcp-hub-corp/[email protected]", "mcp-hub-security"],
        "env": {
          "MCPHUB_API_KEY": "YOUR_API_KEY"
        }
      }
    }
  }
}

{
  "mcpServers": [
    {
      "name": "mcp-hub-security",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/mcp-hub-corp/[email protected]", "mcp-hub-security"],
      "env": {
        "MCPHUB_API_KEY": "YOUR_API_KEY"
      }
    }
  ]
}

Environment variables

MCP servers

Skills

Skills use a tighter analyzer (17 analyzers, 61 rules) that is separate from the MCP server scanner. Using different thresholds for each is intentional.

Optional vars: if you do not want to override a default, omit the variable entirely. Do not set it to the empty string. (The server normalizes "" to the default, but some MCP clients refuse to forward empty-string env entries at all, leading to confusing behavior.)

How it works

MCP server scan pipeline

check_mcp_safety(url) runs four steps automatically:

1. POST /scans/          →  submit repo URL, receive check_token
2. GET  /scans/checking/{token}/  (poll every 2 s, up to 5 min)
3. GET  /scans/{id}/verdict/      →  score, risk, capabilities, findings
4. Policy engine         →  evaluate against your env vars → allowed: true/false

Cached results (same repo + same commit SHA) skip steps 1–3 and cost 0 credits.

Skill scan pipeline

check_skill_safety and check_skill_safety_url are synchronous — no polling needed. The API analyses the SKILL.md content immediately and returns the result in a single request.

Policy engine

The policy engine runs locally after every scan. It blocks if any of these conditions are true:

When blocked, the response includes allowed: false, a human-readable reason, and blocked_by_policy with the list of violations.

Risk levels are ordered: safe = none < low < medium < high < critical.

Why MCPs and Skills have separate thresholds

The MCP server scanner and the Skill scanner are different analyzers with different scoring scales and sensitivity levels. Skills get slightly more permissive defaults (min_score: 70, max_risk: medium) because the skill analyzer is purpose-built for SKILL.md structure and has fewer false positives than the general-purpose MCP scanner. You can tighten skill policy independently of MCP policy.

Credits

Available tools

MCP server tools

Skill tools

Examples

Scan an MCP server before installing it

"Before we add the Playwright MCP, check if it's safe: https://github.com/microsoft/playwright-mcp"

Claude will call check_mcp_safety and report the score, capabilities, OWASP risks, and whether it passes your policy.

allowed: true
security_score: 91
risk_level: low
capabilities: [browser_control, network_egress]
owasp_risks: []
credits_consumed: 0   ← cached result, same commit

Block a server that exceeds your policy

If a repo returns risk_level: high and your MCPHUB_MAX_RISK is low:

allowed: false
reason: "MCP server blocked by security policy: Risk level 'high' exceeds maximum 'low'"
blocked_by_policy: ["Risk level 'high' exceeds maximum 'low'"]

Scan a Skill before running it

"Check if this skill is safe before loading it"

check_skill_safety(content="---\nname: my-skill\ndescription: ...\n---\n...")

Returns:

allowed: true
score: 92
risk_level: low
finding_count: 0
has_critical: false

Re-evaluate policy on an existing scan

Change your policy env vars and re-apply them to a previous scan without consuming credits:

get_verdict(scan_id="550e8400-e29b-41d4-a716-446655440000")

Check your credit balance

get_credit_balance()
# → {"credits": 285, "email": "[email protected]"}

Troubleshooting

Claude Code says "Failed to connect"

That four-word message is everything Claude Code shows by default when an MCP server fails to start. The real error is captured in a debug file but you have to ask for it.

Step 1 — run a health check yourself. From your terminal, run the same command Claude Code runs, but skip stdio and just print the diagnostic table:

MCPHUB_API_KEY=your-key uvx --from git+https://github.com/mcp-hub-corp/[email protected] mcp-hub-security --health

This prints every MCPHUB_* env var the server sees, validates them, and ends with status: OK or status: UNHEALTHY. Exit code 0 means the server can start; exit code 2 means a config problem (missing API key, invalid risk level, malformed URL).

Step 2 — capture the full stderr. Start Claude Code with --debug-file=/tmp/claude.log:

claude --debug-file=/tmp/claude.log

Then tail -f /tmp/claude.log to see every stderr line from every MCP server — including the actual exception that Claude Code is hiding.

Step 3 — for Claude Desktop, logs go to ~/Library/Logs/Claude/mcp-server-mcp-hub-security.log on macOS.

ModuleNotFoundError or stale uvx cache

If you ran an older version once, uvx may have a broken wheel cached. Force a fresh fetch:

uv cache clean mcp-hub-security

Then re-run the original uvx --from [email protected] … command — it will resolve the pinned tag again.

MCPHUB_API_KEY is required

The server now fail-fasts when the API key is missing instead of silently breaking. Set it in the env block of your MCP config (not inline on the command). Get a key at mcp-hub.info/accounts/dashboard/.

Heads-up on empty strings: for any optional MCPHUB_* variable, leave it out entirely instead of setting it to "". Empty strings are normalized to the default, but tooling that round-trips JSON may interpret them inconsistently.

What version am I running?

uvx --from git+https://github.com/mcp-hub-corp/[email protected] mcp-hub-security --version
# → mcp-hub-security 2.0.1