SecureMCP-Lite
Local MCP firewall for AI agents
Go to RepoView on npm
Overview

Getting Started

Fastest path to a working SecureMCP-Lite setup.

Getting Started

This is the fastest path from zero to a working local MCP policy layer.

Goal

By the end of this page you should have:

  • a local secure-mcp.yml
  • a validated policy
  • a working wrapper command
  • a clear understanding of where to plug SecureMCP-Lite into your AI client

1. Install

Quick evaluation with npx

npx securemcp-lite init

This creates a starter secure-mcp.yml in the current directory.

Project-local install

npm install --save-dev securemcp-lite
npx securemcp-lite init --config ./secure-mcp.yml

Use the project-local install if you want:

  • reproducible setup for a team
  • a version-pinned dependency in package.json
  • a repo-level MCP command that different clients can share

2. Start with a safe first policy

For a first rollout, use a read-only policy shape:

version: 1

rateLimit:
  requestsPerMinute: 60

logging:
  level: info
  includeArguments: false

tools:
  allow:
    - read_file
    - list_dir
    - search_files

  parameterRules:
    read_file:
      path:
        allow:
          - '^/absolute/path/to/project(?:/.*)?$'
        deny:
          - '\.\.'

This is a good first step because it gives an agent useful repository visibility without silent write or shell access.

3. Validate the policy before using it

npx securemcp-lite validate-config --config ./secure-mcp.yml

For CI or stricter rollout gates:

npx securemcp-lite validate-config --config ./secure-mcp.yml --strict

Use --strict if you want risky-but-valid configs to fail early instead of slipping into daily use.

4. Start the proxy

Example with the MCP filesystem server:

npx securemcp-lite start \
  --target "npx -y @modelcontextprotocol/server-filesystem ." \
  --target-cwd /absolute/path/to/project \
  --config /absolute/path/to/project/secure-mcp.yml

What this does:

  • SecureMCP-Lite becomes the MCP command your client launches
  • SecureMCP-Lite spawns the real target server behind the scenes
  • every tools/call request is evaluated locally before it reaches the target

5. Point your AI client at the wrapper, not the raw server

Do not configure your AI client to launch the target MCP server directly.

Use this pattern instead:

AI client -> securemcp-lite start -> target MCP server

That is the core product model.

6. Verify the behavior manually

What success should look like:

  • allowed read-only tool calls are forwarded
  • disallowed tools are blocked locally
  • path traversal attempts are blocked locally
  • JSON-RPC logs stay on stdout
  • human-readable logs stay on stderr

7. Run the proof-first demos in this repo

npm install
npm run build
npm run demo:blocked
npm run demo:allowed
npm run demo:session

These demos are bundled with the repository and are intended to prove the product behavior before you wire a real third-party MCP server into your workflow.

8. Pick your client integration guide

Next pages to read: