Installation

Clone and build secure-mcp 2.x, authorize repository roots, and install the strict MCP v2 stdio server and agent workflow for pi, Cursor, or OpenAI Codex.

Installation

secure-mcp runs as a local subprocess over stdio and speaks MCP protocol revision 2026-07-28 only. The client launches the built entrypoint, passes a filesystem allowlist in the environment, and exchanges MCP messages over stdin/stdout.

Requirements

Git
Node.js 20 or newer
pnpm 10
Bash and Python 3 for scripts/install-agents.sh; PowerShell 7 for scripts/install-agents.ps1
One or more existing absolute directories containing repositories you may review
An MCP client that supports protocol revision 2026-07-28

Clone, build, and install in one command

The checkout is the primary distribution channel: it contains the server, installer, master agent skill, fixtures, source, and documentation. The one-command bootstrap installs dependencies, builds the server, prompts for the filesystem allowlist when it is unset, then wires the skill and MCP server into pi, Cursor, and OpenAI Codex and verifies the result:

git clone https://github.com/brbndon/secure-mcp.git
cd secure-mcp
./scripts/setup.sh

On Windows, run .\scripts\setup.ps1 in PowerShell. To skip the prompt, pass the allowlist explicitly: SECURE_MCP_ALLOWED_ROOTS=/absolute/path/to/Code ./scripts/setup.sh. Prefer a parent directory that contains the Swift and web checkouts you review.

What the bootstrap runs (the manual path)

pnpm install --frozen-lockfile
pnpm build
export SECURE_MCP_ALLOWED_ROOTS=/absolute/path/to/repositories
./scripts/install-agents.sh install
./scripts/install-agents.sh check

Filesystem tools fail closed unless SECURE_MCP_ALLOWED_ROOTS names one or more roots that may contain a requested project_root. Use : between multiple roots on macOS/Linux and ; on Windows. Prefer the parent that contains the repositories you review (for example /Users/you/Code) rather than a single app or your home directory. Canonical-path and symlink checks still apply within each authorized root.

check verifies installation. add-root /absolute/path appends another existing directory to an existing install. uninstall removes only entries owned by secure-mcp.

Grok Build TUI is unsupported until it negotiates MCP 2026-07-28. It currently requests 2025-11-25; do not add it to client config. See Client compatibility.

Manual client configuration

If you do not use the installer, point any stdio MCP client that supports protocol 2026-07-28 at the built entrypoint and pass the allowlist:

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

The project_root supplied to a tool must be visible to the machine running the server, fall under an allowed root, and is safest as an absolute path. See Client compatibility for per-client shapes, including VS Code / GitHub Copilot’s top-level servers key.

Server-only npm fallback

After publication, users who only need the stdio server can target the v2 artifact explicitly:

export SECURE_MCP_ALLOWED_ROOTS=/absolute/path/to/repositories
npx -y @brdndon/secure-mcp@2

The npm tarball contains only the compiled server and public project documents. It does not include the agent skill, installer, fixtures, source, or server.json registry metadata.

Development loop

pnpm dev
pnpm test
pnpm verify

pnpm dev runs the MCP server through tsx; it is a stdio process, so logs belong on stderr and the terminal may look quiet while the client is connected.