Heimdall

The watchman at your agent's gate.

A local, pre-flight security scanner for Model Context Protocol (MCP) servers — vet a server, or a whole agent config, before your agent trusts it. No account, no backend, and it never runs the server by default.

MCP servers are unvetted code with a natural-language attack surface: their tool descriptions go straight to your model, and the server runs with your machine's access. Heimdall scores what a server can actually do — not what it claims — and cites the exact evidence. It runs entirely on your machine, needs no account, and never executes the server by default, so you can vet a package before you install it and gate it in CI.

Quickstart

npx mcp-heimdall-scan firecrawl-mcp                   # scan a published server
npx mcp-heimdall-scan ./claude_desktop_config.json    # audit your whole agent config
npx mcp-heimdall-scan firecrawl-mcp --online          # + check its deps for known CVEs (OSV.dev)
npx mcp-heimdall-scan ./my-server --policy strict     # gate it in CI

No install, runs locally, nothing leaves your machine.

Or try it in your browser: caglarbozkurt.github.io/mcp-heimdall — the full scanner runs 100% client-side (npm packages are fetched via jsDelivr; or paste a tools.json / MCP config). No backend, nothing uploaded. Local paths and --handshake need the CLI.

What it checks

Every finding cites file:line or tool:name. Capability ≠ risk: raw power is shown as an informational profile and never fails the scan — only hard gates and real anomalies do.

What makes it different

• Local, and it doesn't run the server. Everything is static and offline by default — no account, no backend, nothing uploaded — and it never executes untrusted code unless you opt into --handshake (documented for a disposable VM only). You vet a package before installing.
• Proves the path. Taint/data-flow turns "reads files AND has network = fail" into a concrete, located flow — so it doesn't cry wolf on a config read plus an unrelated API call.
• Sees the whole gate. It reasons across the set of servers you've configured — the cross-server exfil path neither server shows alone. Most scanners look at one at a time.
• A gate you control. Detectors emit facts; a policy you define turns them into pass / warn / fail. Deny capabilities, require provenance, add audited waivers, gate CI.

Usage

heimdall <target> [options]

--tools <file>     supplement analysis with a tools/list (or {tools,resources,prompts}) dump
--policy <p>       "default", "strict", or a JSON policy file
--baseline <file>  diff against a prior --json report (drift / rug-pull detection)
--handshake        RUN the server(s) for the live tool list (untrusted code — VM/container only)
--online           check declared deps against OSV.dev for known CVEs (sends dep names, not source)
--json             machine-readable report
--sarif            SARIF 2.1.0 (GitHub code-scanning / CI)
--no-fail          always exit 0

Exit codes: 0 pass/warn · 1 fail · 2 error

Policies

Detectors emit facts; a policy turns them into the verdict. Ship the default, pick strict, or write your own procurement/security criteria:

{
  "name": "acme-procurement",
  "denyCapabilities": ["exec", "dynamic-eval", "secret-access"],
  "require": ["has_repository", "has_license"],
  "failOnSeverity": "high",
  "warnOnSeverity": "low",
  "allow": [{ "id": "capability/scope-mismatch", "reason": "reviewed", "expires": "2026-12-31" }]
}

Library

import { scan } from "mcp-heimdall-scan";

const report = await scan("some-mcp-server", { policy: "strict" });
if (report.verdict === "fail") throw new Error(report.reasons.join("; "));

Also ships as a Claude Code skill (skill/) — vet a server in-conversation before installing.

Use it as an MCP server

Give your agent a scan_mcp_server tool so it can vet a server before connecting to it — "scan this before you add it." Add Heimdall to your MCP client config:

{
  "mcpServers": {
    "heimdall": {
      "command": "npx",
      "args": ["-y", "--package", "mcp-heimdall-scan", "heimdall-mcp"]
    }
  }
}

The tool takes target (npm package, pypi:<name>, path, GitHub URL, tools.json, or a client config), plus optional policy and online. It's static-only — it downloads but never executes the server, and the code-execution modes (--handshake, validate) are intentionally not exposed to the agent.

Use it in CI (GitHub Action)

Gate every pull request — scan your MCP config (or a server) and fail the build if it's risky. Add this to .github/workflows/:

- uses: caglarbozkurt/mcp-heimdall@v1
  with:
    target: ./claude_desktop_config.json   # a path, npm/pypi package, github URL, or tools.json
    policy: strict                          # "default", "strict", or a JSON policy file
    online: true                            # also check deps for known CVEs (OSV.dev)
    sarif: heimdall.sarif                   # optional: emit SARIF for code scanning

Runs entirely on your own CI runner — no backend, and free on public repos.

Validate (behavioral cross-check)

Static analysis says what a server can do. heimdall validate checks that against what it actually does — it runs the server with a capability recorder preloaded (hooking fs / net / http(s) / child_process / vm / fetch / process.env), drives each tool, and diffs observed runtime behavior against the static flags:

heimdall validate ./my-server            # one server: confirmed / missed / not-exercised
heimdall validate --list servers.txt     # batch: a recall number over observed behavior

• confirmed — flagged and observed (the static claim held up).
• not exercised — flagged but not triggered by naive args (a lower bound, not proof the flag is wrong).
• missed — observed but not flagged → a real static gap to review (or an incidental library side effect).

So it's trustworthy for finding false negatives (static misses); it does not disprove a flag. Each server runs in a throwaway HOME + working directory with no inherited secrets, but it still runs the server and calls its tools (network/exec side effects) — use a disposable VM/container.