Skip to content
secure-mcp
Esc
↑↓navigate↵open⌘Jpreview

Getting started

Run a review in five steps.

Everything from install to handoff — the commands are real, from the current build.

  1. 01

    Install and build the server

    Requires Node.js 20+ and pnpm (or npm). The build produces the stdio entrypoint used by every MCP client.

    cd secure-mcp
pnpm install
pnpm build
  2. 02

    Authorize repository roots

    Filesystem tools fail closed until you configure the canonical roots they may inspect. Keep the scope as narrow as practical.

    export SECURE_MCP_ALLOWED_ROOTS=/abs/path/repositories
pnpm start
  3. 03

    Connect from your client

    Point any MCP client at the built entrypoint with the filesystem allowlist set. Works in Claude, Cursor, Codex, pi, and other stdio clients.

    {
  "mcpServers": {
    "secure-mcp": {
      "command": "node",
      "args": ["/abs/path/secure-mcp/dist/index.js"],
      "env": {
        "SECURE_MCP_ALLOWED_ROOTS": "/abs/path/repositories"
      }
    }
  }
}
  4. 04

    Install the agent skill

    One script symlinks the master skill into pi, Cursor, and Codex, and wires the server config for each harness.

    ./scripts/install-agents.sh install
./scripts/install-agents.sh check

The audit workflow

Six phases, one mandate.

The recommended sequence keeps scans bounded, guidance stack-aware, and findings confirmed before they reach a human.

  • Phase 1

    Inventory

    secure_mcp_list_project_structure scopes the repository and reports stacks, paths, and coverage.

  • Phase 2

    Architecture and guidance

    secure_mcp_analyze_architecture detects stacks and recommends knowledge packs; secure_mcp_get_knowledge_pack loads them on demand.

  • Phase 3

    Category checks

    Authentication, injection risks, and secrets reviews run in parallel, each returning structured candidates.

  • Phase 4

    Confirmation

    The agent opens each candidate's file at the cited line and confirms the data flow before anything is reported.

  • Phase 5

    Remediation report

    secure_mcp_produce_findings dedupes, filters, and prioritizes findings into a human-facing report.

  • Phase 6

    Handoff

    Executive summary, fix plan, methodology limits, and a retest checklist — no exploit content anywhere.

Coverage honesty

“Not observed” never means “not scanned”.

Every bounded scan returns structured coverage: which paths were included, ignored, excluded, or truncated — and why.

Coverage distinguishes three situations that scanners usually blur together:

  • No candidate found — every reviewed file was checked and nothing matched.
  • Scan truncated — caps were hit and the remaining scope was not reviewed.
  • Candidate pending — heuristics stay candidates until the data flow is confirmed in code.

An empty finding list is never presented as proof that a whole tree was clean. That keeps the report trustworthy — and actionable.

Defensive use policy

Hardening only. By design.

secure-mcp is a defensive, remediation-focused review tool. Its mandate is to identify potential weaknesses, classify them, and recommend concrete remediation.

The server and its skills never do these

  • Generate exploit code or proof-of-concept attack code
  • Offer offensive bypass or weaponization guidance
  • Use discovered secrets against any system
  • Execute target-project code, scripts, or binaries— review is read-only

Use it only on code you own or are explicitly authorized to review.

Common questions

The details that matter.

Why is a filesystem allowlist required?

The allowlist prevents an agent prompt from turning a local MCP server into a general filesystem reader. Set SECURE_MCP_ALLOWED_ROOTSto the narrowest parent directories that contain repositories you intend to review.

How do I confirm a finding in code?

Open the cited file at the cited line, trace the data flow from source to sink, and check runtime configuration. High and critical findings are never reported as confirmed until the evidence is verified this way.

Can I request a stack pack or a tool?

Yes — stack packs and tool coverage evolve on a roadmap. Open a GitHub feature request with the stack or surface you need and where it fits in the defensive audit workflow.

How do I report a product issue?

Provide a minimal reproducible local fixture, the tool and input shape, and the structured coverage report. No live credentials, sensitive source, or exploit code — keep reports focused on containment, read-only behavior, and misleading audit results.

Which stacks are supported?

In v1: TypeScript and Next.js (App Router, Server Actions, middleware) and Swift and SwiftUI, with Expo and React Native detection. More surfaces are planned.

Stuck on something specific? Contact support. Or read the full documentation.