TrustKit MCP Guard

Table of Contents

• Features
• Running
  • From npm
  • Docker (production)
  • From source (development)
• Client Configuration
  • HTTP mode
  • Stdio mode
• Configuration
• License

AI execution firewall for MCP-based tools.

MCP Guard is a proxy that sits between AI clients and MCP servers, enforcing security policies on tool calls. It validates, controls, and audits every tool execution.

Features

• Policy engine — allowlist/denylist rules with glob patterns
• Default deny — block everything not explicitly allowed
• Audit logging — structured JSON events for every decision
• Read-only mode — restrict tools to read operations only

Running

From npm

No build step required. Run directly with npx:

npx @trustkit/mcp-guard --config guard.yaml

Or install globally:

npm install -g @trustkit/mcp-guard
mcp-guard --config guard.yaml

Docker (production)

Use the pre-built image from GitHub Container Registry:

docker run --rm -p 31415:31415 \
  -v ./guard-config:/etc/mcp-guard:ro \
  -v ./guard-data:/data \
  -v ./my-project:/data/project:ro \
  ghcr.io/trustkithq/mcp-guard:latest \
  --config /etc/mcp-guard/guard.yaml

Or use the production compose file:

docker compose -f docker-compose.prod.yaml up

The compose file mounts three volumes:

| Volume | Container path | Purpose | |---|---|---| | ./guard-config/ | /etc/mcp-guard/ | Guard configuration (read-only) | | ./guard-data/ | /data/ | Audit database and persistent state | | ./my-project/ | /data/project/ | Your project files (read-only) |

Edit docker-compose.prod.yaml to adjust paths for your setup.

From source (development)

git clone https://github.com/trustkithq/trustkit-mcp-guard.git
cd trustkit-mcp-guard
pnpm install
pnpm build
node dist/cli.js --config examples/basic-config.yaml

A development compose file is included for building from source:

docker compose build
docker compose up mcp-guard-http    # HTTP mode
docker compose run --rm mcp-guard   # stdio mode

Client Configuration

HTTP mode

The guard listens on a port (default 31415) and AI clients connect via URL. Use this when you want a long-running guard process, persistent audit data, or read-only project access.

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "mcp-guard": {
      "type": "url",
      "url": "http://localhost:31415/mcp"
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "mcp-guard": {
      "url": "http://localhost:31415/mcp"
    }
  }
}

Codex:

codex --mcp-server-uri http://localhost:31415/mcp

Stdio mode

The AI client spawns the guard as a child process. No port to manage, no Docker required.

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "mcp-guard": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@trustkit/mcp-guard", "--config", "guard.yaml"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "mcp-guard": {
      "command": "npx",
      "args": ["-y", "@trustkit/mcp-guard", "--config", "guard.yaml"]
    }
  }
}

Codex:

codex --mcp-server "npx -y @trustkit/mcp-guard --config guard.yaml"

Configuration

See examples/basic-config.yaml for a complete example with stdio transport, and examples/http-config.yaml for HTTP transport.

License

This project is licensed under Apache 2.0.