tool-use-firewall MCP server
Commit Oct 19, 2026Acts as a security proxy between AI agents and MCP servers to enforce policies like rate limiting, argument validation, and human-in-the-loop approvals.
Also known as reaatech/tool-use-firewall
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 19, 2026
- License
- MIT
What is tool-use-firewall MCP?
tool-use-firewall acts as a security proxy between AI agents and MCP servers to enforce policies like rate limiting, argument validation, and human-in-the-loop approvals.
Summary generated from the project's README
About tool-use-firewall MCP server
This security proxy acts as an intermediary between AI agents and MCP servers to protect against dangerous tool invocations. It functions as an interceptor pipeline that evaluates every request through multiple stages, including rate limiting, argument validation, and secret scanning. Developers can deploy it as a stdio proxy or via an HTTP transport to secure connections to databases, filesystems, or network services.
The system provides granular control through a policy engine that supports glob pattern matching and priority-based rules. It includes specialized protections such as SQL injection detection, shell metacharacter blocking, and JSON Schema validation. Users can also implement human-in-the-loop approval workflows using an HTTP API, webhooks, or integrations with Slack and Discord to verify sensitive actions before they reach the upstream server.
Setup involves configuring a YAML policy file and pointing your MCP client to the firewall instead of the direct server. It supports advanced operational modes like a dry-run shadow mode for testing rules without enforcement, and a global read-only toggle for emergency safety. The tool is built with TypeScript and requires Node.js version 20 or higher.
What you can do with it
- 1Manage operational costsSet budget limits for AI sessions to prevent excessive spending on expensive tool calls.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
APPROVAL_API_TOKEN
| Name | Description | |
|---|---|---|
| APPROVAL_API_TOKEN | — |
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablereaatech/tool-use-firewall is public and reachablegithub.com/reaatech/tool-use-firewall ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-19github.com/reaatech/tool-use-firewall ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubtool-use-firewall
Policy enforcement layer between AI agents and MCP servers — intercept, validate, and secure every tool call before it reaches the upstream.
Why tool-use-firewall?
AI agents are powerful, but they can also be dangerous. A single errant DROP TABLE or rm -rf / can destroy hours of work. This project sits between your AI agent and your MCP servers, acting as a security guard for every tool invocation — rate limiting, argument validation, cost tracking, read-only enforcement, and human-in-the-loop approval chains.
If you're deploying AI agents that talk to databases, filesystems, or any MCP server, this is your safety net.
Architecture
┌─────────────────┐ ┌──────────────────────┐ ┌─────────────────┐
│ AI Agent │────▶│ tool-use-firewall │────▶│ Upstream MCP │
│ (Claude, │ │ (Interceptor │ │ Server │
│ GPT, etc.) │◀────│ Pipeline) │◀────│ (Database, │
└─────────────────┘ └──────────────────────┘ │ Filesystem, │
│ Network, etc.) │
└─────────────────┘
The interceptor pipeline enforces policies in strict order:
Request → Rate Limiter → Cost Tracker → Secret Scanner → Argument Validator
→ Schema Validator → Policy Engine → Read-Only Check → Anomaly Detector
→ Approval Workflow → Audit Logger → Upstream
Stages are registered only when enabled in the policy (e.g. secret scanning, schema validation, and anomaly detection are opt-in). Inbound JSON-RPC frames may be single messages or batches (top-level arrays); each tools/call in a batch is intercepted independently.
Data flow details and state management: ARCHITECTURE.md
Features
Policy Engine
- Rule evaluation — Block, allow, or require approval by tool name, argument values, and custom conditions
- Priority-based matching — Rules evaluated in priority order; first match wins
- Glob pattern matching —
db.*matchesdb.execute,db.query, etc.
Rate Limiting
- Token bucket algorithm — Global, per-tool, and per-session limits
- Bounded memory — TTL-based eviction prevents memory exhaustion
- Burst capacity — Configurable burst allowance for traffic spikes
Argument Validation
- SQL injection detection — Pattern matching against known dangerous patterns
- Shell injection prevention — Blocks metacharacters like
;,&&,`,$() - Custom regex patterns — User-defined validation per tool/argument
- JSON Schema validation — Validate
tools/callarguments against the upstream's advertisedinputSchema - ReDoS protection — All regex patterns validated for safety before compilation
Secret Scanning
- Outbound secret detection — Block tool calls whose arguments contain API keys, tokens, or other secrets
- Custom patterns — Define named patterns per deployment
Anomaly Detection
- Behavioral baselines — Flags tool calls that deviate from a session's recent pattern
- Configurable sensitivity — Tune the window size and threshold per policy
Read-Only Mode
- Global toggle — Block all write operations when enabled
- Per-tool exceptions — Allow-list for read-only safe tools
- Break-glass tokens — Timing-safe bypass for emergencies
Cost Tracking
- Per-session budgets — Enforce cost limits for expensive tool calls
- Tool-level pricing — Assign costs per invocation
- Configurable action — Block or warn when budget exceeded
Approval Workflows
- Multi-level chains — Require approval from multiple groups
- Timeout handling — Expired approvals automatically denied
- Multiple interfaces — HTTP API, CLI prompts, webhook, Slack, and Discord notifications
- Auto-approval — Optionally auto-approve trusted tools after a threshold of safe calls
- Rate-limited API — Per-IP token bucket on the approval HTTP endpoint
Audit Logging
- Structured JSON — Every decision recorded with full context
- Sensitive data redaction — API keys, tokens, emails automatically redacted
- Level control —
none,summary, orfullverbosity - File & sidecar output — Write events to a rotating local file (daily/size rotation, max-files retention, gzip) and/or forward them over HTTP to a sidecar/SIEM endpoint (stdout is reserved for the MCP JSON-RPC stream)
Transports & Routing
- stdio & HTTP — Run as a stdio proxy (default) or expose an HTTP transport
- Multi-upstream — Route tools to different upstream MCP servers by glob pattern
- Time windows — Restrict rules to specific days/hours with timezone support
Operations
- Policy hot-reload — Edits to the policy file are picked up without a restart
- Dry-run / shadow mode — Log what would be blocked without enforcing
- Prometheus metrics — Optional
/metricsendpoint (requests, blocks, approvals, latency) --initscaffolding — Generate a starter policy from the upstream'stools/list--validatelinting — Validate a policy (schema + ReDoS) in CI without booting the proxy
Installation
The published entry point is tool-use-firewall, which ships the tool-use-firewall binary and pulls in the @reaatech/tool-use-firewall-* packages. Run it without installing via npx:
npx tool-use-firewall \
--config ./policy.yaml \
--upstream node ./my-mcp-server.js
Or install the CLI globally:
npm install -g tool-use-firewall
tool-use-firewall --config ./policy.yaml --upstream node ./my-mcp-server.js
Requires Node.js ≥ 20.
tool-use-firewallis a thin alias for@reaatech/tool-use-firewall-server— use whichever name you prefer. For a narrower dependency surface, import the scoped@reaatech/tool-use-firewall-*packages directly.
Quick start
Generate a starter policy from your upstream server's tool list, then run the firewall against it:
# 1. Scaffold a policy.generated.yaml from the upstream's tools/list
tool-use-firewall --init --upstream node ./my-mcp-server.js
# 2. Validate it (schema + ReDoS checks) — exits non-zero on failure, good for CI
tool-use-firewall --validate ./policy.generated.yaml
# 3. Run the proxy
tool-use-firewall --config ./policy.generated.yaml --upstream node ./my-mcp-server.js
To plug into an MCP client (e.g. Claude Desktop), point the client at the firewall instead of the upstream:
{
"mcpServers": {
"my-server": {
"command": "npx",
"args": [
"@reaatech/tool-use-firewall-server",
"--config", "/abs/path/to/policy.yaml",
"--upstream", "node",
"--", "/abs/path/to/my-mcp-server.js"
]
}
}
}
With the human-in-the-loop approval API enabled:
export APPROVAL_API_TOKEN="$(openssl rand -hex 32)"
tool-use-firewall \
--config ./policy.yaml \
--upstream node ./my-mcp-server.js \
--approval-port 8080
Use --upstream-args for container/scripted environments where the upstream command and its args are a single string:
tool-use-firewall --config ./policy.yaml --upstream node --upstream-args "./my-mcp-server.js --port 9000"
Programmatic use
import { MCPProxyServer } from '@reaatech/tool-use-firewall-server';
const server = new MCPProxyServer({
policyPath: './policy.yaml',
upstreamCommand: 'node',
upstreamArgs: ['./my-mcp-server.js'],
});
await server.start();
From source (contributors)
git clone https://github.com/reaatech/tool-use-firewall.git
cd tool-use-firewall
pnpm install
pnpm build
pnpm test
# Run the local build against an example upstream
pnpm dev -- --config ./policies/default.yaml --upstream node ./examples/basic-proxy/upstream-server.js
CLI reference
tool-use-firewall --config <path> --upstream <command> [options]
| Flag | Description |
|---|---|
--config, -c <path> |
Path to the policy YAML file (required to run the proxy) |
--upstream, -u <command> |
Command to spawn the upstream MCP server (required to run the proxy) |
--upstream-args <string> |
Space-separated args for the upstream, for scripted environments |
--approval-port <port> |
Port for the human-in-the-loop approval HTTP API |
--http-port <port> |
Port for the HTTP transport |
--dry-run |
Shadow mode: log what would be blocked without enforcing |
--init |
Scaffold a policy.generated.yaml from the upstream's tools/list |
--validate <path> |
Validate a policy (schema + ReDoS) and exit non-zero on failure |
--help, -h |
Show help |
--version, -v |
Show version |
Arguments after a literal -- are forwarded to the upstream:
tool-use-firewall --config p.yaml --upstream node -- ./mcp-server.js --port 9000
Packages
| Package | Description | Dependencies |
|---|---|---|
core |
Types, error classes, logger, redactor, safe-regex | (none) |
config |
Policy YAML schema (Zod) and loader | core, yaml, zod |
policies |
Policy engine, rate limiter, cost tracker, validators | core, config |
approvals |
Approval workflow, HTTP API, CLI/webhook approvers | core, config, policies, express, zod |
audit |
Audit logging with redaction | core, config |
server |
MCP proxy server, CLI, interceptor pipeline | core, config, policies, approvals, audit |
Policy Configuration
See policies/ for example YAML files:
| Policy | Description |
|---|---|
default.yaml |
Sensible defaults — rate limits, SQL safety, shell safety |
database-safe.yaml |
Database-focused policy with strict SQL validation |
read-only.yaml |
Read-only mode with bypass token support |
Documentation
| Document | Content |
|---|---|
| ARCHITECTURE.md | System design, pipeline flow, resource management |
| CONTRIBUTING.md | Development setup, conventional commits, PR process |
| AGENTS.md | Coding conventions and guidance for AI agents |
| SECURITY.md | Security policy and vulnerability reporting |
Tech Stack
| Layer | Technology |
|---|---|
| Language | TypeScript 5.8 (strict mode) |
| Runtime | Node.js ≥ 20 |
| Package manager | pnpm 10 (workspaces) |
| Build | tsup + Turborepo |
| Lint & format | Biome |
| Testing | Vitest |
| Validation | Zod |
| Schema | YAML |
Contributing
Contributions are welcome. See CONTRIBUTING.md for the full workflow:
- Fork the repo, create a feature branch
- Write code with tests (
vitest), lint withbiome - Run
pnpm lint && pnpm testbefore committing - Use Conventional Commits
- Open a PR
License
tool-use-firewall MCP questions
What does tool-use-firewall do?
It serves as a policy enforcement layer between AI agents and MCP servers, intercepting and validating tool calls for security and cost control.
How can I approve dangerous tool calls?
The system supports human-in-the-loop approval workflows through multiple interfaces including HTTP API, CLI prompts, webhooks, Slack, and Discord.