SecureMCP-Lite

Lightweight local MCP firewall for AI agents.
Policy-driven, stdio-first, easy to adopt, built for real developer workflows.

Protect MCP tool calls before they reach the target server.

Maintained by Samuel Indra Bastian.

What this is

SecureMCP-Lite is a lightweight local proxy firewall for MCP servers. It sits between an MCP client and a target MCP server, inspects stdio JSON-RPC traffic in real time, and enforces a local YAML policy before risky tool calls reach the upstream server.

It is designed for developers and teams who want to keep using MCP-enabled AI tools without giving those tools unrestricted access to local files, shell commands, or other powerful operations.

Why this matters

Many MCP workflows are useful precisely because they expose powerful tools. That also makes them risky.

SecureMCP-Lite helps reduce risk from:

• prompt injection that triggers dangerous tools
• over-permissioned filesystem or shell servers
• accidental destructive actions
• path traversal attempts
• runaway loops that spam tools
• AI agent configurations that are too open by default

What you get

• stdio-first MCP proxy
• YAML policy enforcement with secure-mcp.yml
• tool allowlist
• regex-based argument restrictions
• local JSON-RPC block responses
• readable stderr logging for ALLOWED and BLOCKED
• in-memory request throttling
• npx-friendly CLI
• example policies and integration configs
• executable demos bundled in the repo
• a full docs website under apps/frontend

Who this is for

• solo developers using Claude Code, Codex, Cursor, or Copilot with MCP
• OSS maintainers who want safer repo exploration and demo defaults
• platform and security engineers reviewing AI tool boundaries
• teams that want one shared MCP policy checked into the repository

Supported today vs later

Supported today

• local stdio MCP clients
• local stdio MCP servers
• policy enforcement on tools/call
• repo-local and terminal-first workflows

Not supported yet

• HTTP or Streamable HTTP transport for SecureMCP-Lite itself
• remote MCP hosting
• GUI or TUI approval workflow
• schema-aware validation for every possible tool

That means SecureMCP-Lite is a strong fit today for clients that can launch local stdio MCP servers. It is not yet a drop-in server for remote-only MCP platforms.

Best way to read the docs

The repository includes a full docs website:

• source: apps/frontend
• local run command: npm run site:dev

Primary docs entry points:

• website docs hub: /docs in the Next.js app
• getting started: docs/getting-started.md
• feature overview: docs/feature-overview.md
• compatibility matrix: docs/compatibility-matrix.md
• demo playbook: docs/demo-playbook.md
• integrations index: docs/integrations.md

Installation

Quick evaluation with npx

npx securemcp-lite init
npx securemcp-lite validate-config --config ./secure-mcp.yml
npx securemcp-lite start --target "npx -y @modelcontextprotocol/server-filesystem ." --target-cwd . --config ./secure-mcp.yml

Project-local install

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

Recommended follow-up:

{
  "scripts": {
    "mcp:repo-guard": "securemcp-lite start --target \"npx -y @modelcontextprotocol/server-filesystem .\" --target-cwd . --config ./secure-mcp.yml"
  }
}

That gives your team one stable command for Claude Code, Codex, Cursor, Copilot Chat, or Copilot CLI to call.

Verified demos in this repo

These are not placeholders. They run against bundled fixtures and are verified locally in this repository.

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

What they prove:

• demo:blocked: blocked request never reaches the target
• demo:allowed: allowed request is forwarded and returns a result
• demo:session: realistic MCP flow with initialize, tools/list, and tools/call

Docs site

Run the website locally:

npm install
npm run site:dev

Build it:

npm run site:build

If this is the first time you cloned the repo, npm install at the repository root is enough. The docs site lives under the workspace package at apps/frontend.

The website is meant to be the polished public-facing documentation surface for:

• product overview
• use cases
• compatibility guidance
• integration steps for real AI clients
• install and adoption guidance

Integrations covered

This repository now includes dedicated docs for:

• Claude Code
• Codex
• Cursor
• Antigravity
• GitHub Copilot Chat
• GitHub Copilot CLI
• custom local AI agents or internal tools
• ChatGPT Developer mode
• Anthropic Messages API MCP connector

Important distinction:

• local stdio clients are supported today
• remote-only MCP surfaces such as ChatGPT Developer mode or Anthropic’s API MCP connector require remote HTTP/SSE MCP servers, so SecureMCP-Lite does not plug into those directly in the current stdio-only MVP

That limitation is documented clearly on purpose. Credibility is more important than pretending everything is already supported.

Quick compatibility summary

Client / platform	Local stdio fit today	Notes
Claude Code	Yes	Strong fit for current MVP
Codex CLI / IDE extension	Yes	Strong fit for current MVP
Cursor	Yes	Strong fit for current MVP
Antigravity	Likely yes	Uses raw MCP config flow; documented with caveat
GitHub Copilot Chat	Yes	Local MCP config supported in editor integrations
GitHub Copilot CLI	Yes	Local MCP servers supported
ChatGPT Developer mode	No, not directly	Remote HTTP/SSE only
Anthropic Messages API MCP connector	No, not directly	Remote HTTP/SSE only

See the full details in docs/compatibility-matrix.md.

Website-first documentation strategy

The README is intentionally shorter than the full documentation site.

Use the README to understand:

• what SecureMCP-Lite is
• whether it fits your workflow
• how to install it quickly
• where to read the deeper docs

Use the site and docs folder to understand:

• detailed integrations
• compatibility constraints
• use-case recipes
• adoption guidance for teams

Development

Core package:

npm run lint
npm run build
npm run test -- --run
npm pack --dry-run

Docs website:

npm run site:dev
npm run site:build

Open-source posture

SecureMCP-Lite is built to feel:

• trustworthy
• boring in a good way
• easy to adopt
• useful immediately
• maintainable by a solo maintainer

That is the bar for this project.