---
title: Installation
description: 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.
sidebar:
  label: Installation
  order: 2
---

## 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:

```bash
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)

```bash
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](/docs/clients).

## 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:

```json
{
  "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](/docs/clients) for per-client shapes, including VS Code / GitHub Copilot's top-level `servers` key.

:::note
The npm package `@brdndon/secure-mcp` is server-only and does not include the agent skill or installer. Prefer the checkout path for the complete workflow.
:::

## Server-only npm fallback

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

```bash
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.

:::tip
Run `pnpm smoke` after building to confirm the server starts, negotiates protocol `2026-07-28`, lists its tools, and can analyze the included fixture without executing it.
:::

## Development loop

```bash
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.