Toolfence logo

Toolfence

Community
jiangkoumo

Local, fail-closed policy enforcement and human approval for MCP tool calls.

Publisherjiangkoumo
Repositorytoolfence
LanguageTypeScript
Forks
0
Stars
100
Available tools
0
Transport typestdio
Categories
LicenseMIT
Links
  • Connect tools to AI workflows

    Toolfence exposes MCP capabilities that can be used by compatible AI clients and agents.

  • 0 available tools

    Browse the callable actions below, including names and descriptions when provided by the server.

  • Ready-to-copy setup

    Use the installation snippets to configure this server in your preferred MCP client.

  • Open source signals

    100 stars and 0 forks from the linked repository.

ToolFence

CI npm version npm downloads license

A vendor-neutral policy firewall for MCP tool calls.

ToolFence enforces one testable least-privilege policy between AI agents and stdio MCP servers. With a conservative default (ask or deny), the same rules can be used from Codex, Cursor, or Claude Desktop: safe calls pass, dangerous or unrecognized calls stop before upstream execution, and uncertain calls require human approval—without changing the MCP host or server.

  • Portable policy: keep resource and command rules independent of a single Agent platform.
  • Deterministic enforcement: normalize tool calls, give deny precedence, and surface unknown or ambiguous actions for conservative policy handling.
  • Auditable evidence: record privacy-conscious decisions and result hashes without storing raw arguments or results.

Same MCP call. Different outcome.

ToolFence blocks a synthetic .env leak before it reaches the MCP server

The animation sends the same .env read to the official Filesystem MCP Server twice:

  • without ToolFence, the server returns the explicitly synthetic value OPENAI_API_KEY=TF_DEMO_ONLY;
  • with ToolFence, the protect-secrets rule denies the call before upstream execution;
  • the demo verifies that the denied response and audit log do not contain the synthetic secret.

These are real JSON-RPC processes and assertions, not hard-coded policy results. Run the comparison or regenerate the GIF.

Protect a Filesystem MCP server in three minutes

The npm package is toolfence-mcp; the installed command is toolfence.

bash
npm install -g toolfence-mcp
cd /absolute/path/project
toolfence policy init --list-recipes
toolfence policy init --recipe filesystem
toolfence policy check --policy ./toolfence.yaml

The npm command is the recommended one-step install. Each GitHub Release also attaches the same installable .tgz; after downloading it, run npm install -g ./toolfence-mcp-<version>.tgz. The automatically generated GitHub “Source code” archives are repository snapshots, not installers.

Wrap a local Filesystem MCP server:

bash
toolfence wrap \
  --policy ./toolfence.yaml \
  --server filesystem \
  --workspace "$PWD" \
  -- npx -y @modelcontextprotocol/server-filesystem "$PWD"

The generated policy is conservative and never replaces an existing file. Explore pre-tested policy templates in examples/recipes/ for Filesystem, GitHub, Fetch, SQLite, PostgreSQL, and Git.

Connect the wrapper to your MCP host with one command:

bash
# Preview or write configuration for your favorite host
toolfence host init --host cursor --write
toolfence host init --host claude-desktop --write
toolfence host init --host codex --write
toolfence host init --host claude-code --write
HostGuide or referenceQuick command
Cursordocs/cursor.mdtoolfence host init --host cursor --write
Claude Desktopdocs/claude-desktop.mdtoolfence host init --host claude-desktop --write
Codexdocs/codex.mdtoolfence host init --host codex --write
Claude CodeClaude Code MCP referencetoolfence host init --host claude-code --write

What ToolFence adds

  • Semantic policies & recipes: normalize common Filesystem, Shell, Git, and HTTP tool calls into operations such as fs.read, shell.exec, git.write, and net.request. Choose from built-in recipes or customize matches for paths, commands, hosts, and HTTP methods.
  • Output Secret Redaction (DLP): automatically detect and redact leaked API keys (OpenAI, Anthropic, GitHub, AWS), JWTs, and private keys from tracked upstream tool outputs before reaching the agent, without intentionally recording raw payloads in the audit log.
  • Deterministic enforcement: deny overrides other matches, multi-resource requests are evaluated as a unit, and unknown or ambiguous actions normalize conservatively for policy evaluation.
  • Human approval: use an authenticated local Broker for one-time or session decisions; session approvals are bound to the tool Schema and are invalidated when that Schema changes.
  • Privacy-conscious auditing: record tool identity, affected resources, policy decisions, and result hashes without storing raw arguments or results.
  • Policies you can test: generate, validate, explain, and regression-test YAML policies from the CLI.

Where ToolFence fits

LayerWhat it controlsWhat it does not control
MCP host approvalsHost-specific user prompts and tool settingsA reusable policy shared across different hosts
ToolFenceNormalized tool calls, deterministic YAML policy, Schema-bound approval, privacy-conscious auditDirect actions taken by the upstream server process
OS sandbox or containerProcess, filesystem, environment, and network accessSemantic intent of an MCP tool call by itself

ToolFence is designed to complement host approvals and OS isolation. It is not a replacement for either.

ToolFence architecture

Status

Version 0.4.0 establishes the cross-platform enforcement baseline: a platform-neutral Broker IPC abstraction with user-scoped Windows Named Pipe support, private credential storage enforcement without misleading POSIX mode emulation, a versioned action model (1.0) with conservative downgrade rules, a versioned audit evidence schema (v1) correlating Host, protocol revision, tool fingerprints, and non-forwarding evidence, and Host-native tool bypass disclosures for Codex, Cursor, Claude Code, and Claude Desktop. This builds on the reproducible protocol conformance evidence, cancellation-safe Broker handling, precise approval and dispatch evidence, MCP isError result semantics, and conservative AgentTape integration.

ToolFence is not a sandbox for a malicious MCP server process: the upstream process still runs with the current user's operating-system permissions.

Because ToolFence launches user-configured processes and mediates Shell, Git, and HTTP capabilities, the npm package is transparently declared as dual-use. See DISCLOSURE for the intended legitimate use and security boundary.

Human approval

ToolFence reserves stdout for MCP JSON-RPC messages. Diagnostics and upstream stderr stay on stderr. Start the per-user Broker and approval terminal in separate terminals:

bash
toolfence broker
toolfence approvals

wrap uses the Broker by default. If it is missing, incompatible, unauthenticated, disconnected, or times out, an ask decision fails closed. Use --approval tty only when direct /dev/tty approval is desired. toolfence status verifies Broker connectivity, protocol version, and Socket permissions.

Diagnose a local setup before connecting it to an MCP host:

bash
toolfence doctor --policy ./toolfence.yaml
toolfence doctor --policy ./toolfence.yaml -- \
  npx -y @modelcontextprotocol/server-filesystem "$PWD"
toolfence doctor --policy ./toolfence.yaml --json

doctor checks the Node.js runtime, validates the selected Policy, authenticates a running Broker and verifies its private runtime permissions, and optionally starts the explicit command after -- for a short startup probe. Warnings identify checks that were not requested or services that are not currently running; failed checks exit non-zero.

For scripts or an external approval UI, list the privacy-safe queue as JSON or resolve one known approval ID without a prompt:

bash
toolfence approvals --json
toolfence approvals --id <approval-id> --decision allow-once
toolfence approvals --id <approval-id> --decision allow-session
toolfence approvals --id <approval-id> --decision deny

Policy

yaml
version: 1
default: ask

rules:
  - id: deny-dotenv
    effect: deny
    operations: [fs.read, fs.write]
    resources: ["**/.env", "**/.env.*"]

  - id: allow-workspace-read
    effect: allow
    operations: [fs.read]
    resources: ["${workspace}/**"]

  - id: allow-tests
    effect: allow
    operations: [shell.exec]
    commands:
      - [npm, test]

  - id: allow-git-inspection
    effect: allow
    operations: [git.read]

  - id: allow-read-api
    effect: allow
    operations: [net.request]
    hosts: ["api.example.com", "*.internal.example.com"]
    methods: [GET, HEAD]

Rules are evaluated deterministically:

  1. Every matching deny rule overrides all other matches. A deny resource rule matches when any requested resource is protected.
  2. Otherwise, the first matching rule wins.
  3. If nothing matches, default is used.

Allow and ask resource rules require every requested resource to match, so a multi-file call cannot use one allowed path to carry an unauthorized path.

Filesystem paths are canonicalized before matching, including existing symbolic links. Exact argv matching is used for allowed commands; compound or quoted shell strings are not treated as safe argv and, without an explicit matching rule, require approval instead of inheriting default: allow.

Current operations are fs.read, fs.write, fs.delete, shell.exec, git.read, git.write, git.remote, net.request, and unknown. Ambiguous Git commands, invalid URLs, and unrecognized tools fall back through shell.exec or unknown instead of being treated as a known safe action.

The AgentTape integration is normalized conservatively only for the agenttape, agenttape-fenced, and agenttape_fenced server aliases: list_tapes, inspect_tape, and fork_run are fs.read; save_regression is fs.write scoped to workspaceRoot/tests/agenttape/<filename>. The same tool names from other servers and unrecognized AgentTape tools remain unknown.

As of v0.3.2, an unmatched unknown, ambiguous, or malformed action requires approval instead of inheriting default: allow, while an explicit matching rule can still authorize it. Users remaining on v0.3.1 should use ask or deny as their default.

Output secret redaction is enabled by default for tracked tool results, including successful results and JSON-RPC errors. Set redactSecrets: false at the top level of a policy only when exact upstream output compatibility is required. Detection is best-effort and covers known token formats, private keys, textual secret assignments, and structured string fields with sensitive names; it does not replace destination controls or process isolation.

Policy development

bash
toolfence policy init [--policy ./toolfence.yaml]
toolfence policy check --policy ./examples/policy.yaml
toolfence policy explain --policy ./examples/policy.yaml --action ./action.json
toolfence policy test --policy ./examples/policy.yaml --cases ./policy-cases.yaml

init creates a conservative policy without overwriting an existing file. check validates YAML, strict Schema rules, variables, duplicate IDs, and invalid network-field combinations. explain prints matched rules and the final decision. test runs declarative cases and exits non-zero on any mismatch.

Audit log

The default audit file is .toolfence/audit.jsonl under the workspace. It records operation names, affected paths, tool identity, final policy decisions, and SHA-256 hashes of upstream results. Decision/result records carry proxyRunId and clientSessionId; approval decisions additionally carry approvalId and the actual allow-once, allow-session, or deny resolution. A denied or timed-out call records dispatch: not-forwarded. Allowed decisions do not claim successful dispatch before the upstream write; a correlated result is the evidence that an upstream response returned. Raw tool arguments, command arguments, and raw results are intentionally omitted to reduce secret leakage.

Use --audit /path/to/audit.jsonl to select a different path.

Inspect the default or a selected audit log without storing additional data:

bash
toolfence audit summary
toolfence audit summary --audit /path/to/audit.jsonl --json
toolfence audit tail --lines 20
toolfence audit tail --audit /path/to/audit.jsonl --lines 50 --json

summary reports decision effects, result errors, and operation counts. tail returns the newest validated records using only the documented privacy-safe JSONL fields.

Security boundary

ToolFence reduces accidental or prompt-injected tool misuse when the tool call crosses its stdio proxy. It does not prevent the upstream server process from directly reading files, environment variables, or the network. Process isolation, environment filtering, and network controls require a separate sandbox layer.

Additional current limitations:

  • stdio transport only
  • local Broker support is POSIX-only; Windows remains non-interactive and fail-closed
  • JSON-RPC batch messages are rejected
  • output secret detection is best-effort; unrecognized or encoded secret formats may still pass through
  • an HTTP MCP adapter must expose a redirect destination (for example as redirectUrl) for ToolFence to re-evaluate it

Protocol compatibility

ToolFence's proxy transport is stdio. The supported stdio protocol revisions and their evidence live in the machine-readable conformance/matrix.json; the dated run results are recorded in conformance/report.json, regenerated by npm run conformance and enforced by npm run release:check.

Every matrix row and Doctor report uses one of four statuses:

  • supported — the row passes the shared conformance corpus (conformance/corpus.mjs) in a dated report;
  • experimental — allowed but not yet corpus-verified;
  • unverified — no current passing evidence;
  • unsupported — not implemented (for example Windows interactive Broker and Streamable HTTP).

Unverified and unsupported combinations never expand permissions: policy decisions are deterministic and protocol-revision metadata is neutral for every protocol shape, an unknown or ambiguous action cannot inherit default: allow, and a request advertising an unverified protocol revision produces the same decision and forwarding as the verified revision. Conformance fixtures prove transparent pass-through of server/discover, per-request _meta, list cache metadata, and MRTR; they do not mean ToolFence implements those higher-level capabilities.

Development

The architecture, threat model, historical implementation baselines, and current release gates are maintained in the development guide. Public priorities and good first contribution candidates are in the roadmap. Mutual AgentTape × ToolFence dogfooding follows the mirrored alignment contract.

bash
npm run typecheck
npm test
npm run test:coverage
npm run build
npm pack --dry-run
npm audit --omit=dev

The full validation strategy is in TESTING.md, and the release/security review record is in REVIEW.md. See CONTRIBUTING.md, SECURITY.md, CHANGELOG.md, and RELEASING.md before contributing, reporting a vulnerability, or publishing a release.

License

MIT

Installation

TypingMind
{
  "mcpServers": {
    "toolfence": {
      "command": "toolfence",
      "args": []
    }
  }
}

Use Toolfence MCP with multiple AI models

TypingMind connects MCP tools at the workspace level, so once Toolfence is connected, you can use it with different AI models in TypingMind instead of setting it up separately for each model. This MCP runs locally through the TypingMind MCP connector on your device.

Setup guide to use the local connector

Use this when the MCP server needs access to local files, apps, or private resources on your computer.

1

Open the MCP settings

In TypingMind, go to Settings, Advanced Settings, then Model Context Protocol and choose Setup Connector.

  1. Open TypingMind in your browser.
  2. Click the Settings icon.
  3. Go to Advanced Settings.
  4. Open the Model Context Protocol section.
  5. Click Setup Connector and choose This Device.
TypingMind MCP connector setup screen with This Device selected
2

Run the connector command

Choose This Device, copy the command from TypingMind, and run it in Terminal. Keep the process running while you use MCP.

  1. Copy the setup command shown by TypingMind.
  2. Open Terminal on macOS or Windows Terminal on Windows.
  3. Paste and run the command.
  4. Approve the package install if Terminal asks you to proceed.
  5. Keep the Terminal window running while using MCP tools.
3

Add Toolfence as a server

When the connector status is Ready, click Edit Servers and paste the MCP server configuration.

  1. Wait until the connector status shows Ready.
  2. Click Edit Servers.
  3. Paste the Toolfence MCP server configuration.
  4. Save the server list.
  5. Refresh if you want to confirm the connector is still ready.
TypingMind MCP settings showing active server and Edit Servers button
{
  "mcpServers": {
    "toolfence": {
      "command": "npx",
      "args": [
        "-y",
        "toolfence-mcp"
      ]
    }
  }
}
4

Use it across models

Save the server list, open Plugins, enable the Toolfence MCP tools, then select any supported AI model in TypingMind and use the tools in chat or assign them to an AI agent.

  1. Open the Plugins page in TypingMind.
  2. Enable the Toolfence MCP tools.
  3. Start a chat and choose the AI model you want to use.
  4. Use the MCP tools in chat or assign them to an AI agent.
  5. Switch to another AI model whenever needed without reconnecting MCP.
TypingMind chat using enabled MCP tools with a selected AI model
Can you use Toolfence to help me with this task?
Toolfence
Sure. I read it.
Here is what I found using Toolfence.

Frequently asked questions

What is the Toolfence MCP server used for?

Toolfence is an MCP server that lets compatible AI clients connect to external tools and context. In TypingMind, you can add this MCP server once and make its tools available in your AI workspace.

Can I use Toolfence MCP with multiple AI models in TypingMind?

Yes. TypingMind connects MCP tools at the workspace level, so you can use Toolfence with different AI models such as Claude, ChatGPT, Gemini, or other models you have configured in TypingMind without setting up the MCP server separately for each model.

Why use Toolfence MCP with TypingMind?

TypingMind is one of the best frontends for LLM chat because it brings multiple AI models, prompts, plugins, AI agents, API keys, and MCP tools into one workspace. With Toolfence connected, you can use its MCP tools across your preferred models while keeping your chat workflow organized in TypingMind.

How do I connect Toolfence MCP to TypingMind?

Toolfence runs through the TypingMind local MCP connector. This is best when the MCP server needs access to local files, desktop apps, command-line tools, or private resources on your computer.

What tools does Toolfence MCP provide in TypingMind?

Toolfence exposes MCP capabilities that can be enabled from the TypingMind Plugins page and used in chat or assigned to AI agents.

Do I need to share my API keys with TypingMind to use Toolfence MCP?

No. TypingMind is local-first and lets you keep your model providers, API keys, prompts, and MCP configuration under your control. If Toolfence requires authentication, add the required headers, OAuth settings, or local configuration for that MCP server when you create the connection.

Related MCP Servers

View all

Set up your own AI workspace now

Get notified about new features and future giveaways by subscribing to our newsletter 👇