# Cordon [Health: Active] **Category:** 📊 Monitoring **Repository:** https://github.com/marras0914/cordon **GitHub Stars:** 1 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/cordon ## Description Security gateway for MCP. Policy enforcement, audit logging, human-in-the-loop approvals. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "cordon": { "command": "npx", "args": ["-y","@getcordon/cli"] } } ``` ## Documentation & README

Cordon for MCP

The Security Gateway for MCP Tool Calls

Website • Writeup

Quickstart • Why Cordon • How It Works • Configuration • Roadmap • Contributing

npm version license stars

--- > Every company wants to deploy AI agents. No company is willing to give an agent the keys to their database. > > **Cordon closes the trust gap.**

From the maintainer of Agent Toolbelt — 25+ MCP tools, ~1,600 weekly npm downloads.

--- ## Demo https://github.com/user-attachments/assets/153d978f-6303-443a-b49b-b4ec7ebf0452 --- ## The Problem The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) has made it trivially easy to give AI agents access to powerful tools — databases, file systems, APIs, cloud infrastructure. But MCP has **no built-in security model**. No audit logs. No approval workflows. No rate limits. Today, an AI agent is either **off** or **full admin**. There is nothing in between. This is the single biggest blocker preventing AI agents from reaching production. ## The Solution **Cordon is the security gateway that sits between the LLM and your MCP servers.** It acts as a **firewall**, an **auditor**, and a **remote control** — giving you complete visibility and authority over what your AI agents can and cannot do. ``` ┌─────────┐ ┌──────────┐ ┌──────────────┐ │ LLM / │ ──▶ │ Cordon │ ──▶ │ MCP Server │ │ Agent │ ◀── │ Gateway │ ◀── │ (database, │ └─────────┘ └──────────┘ │ fs, APIs) │ │ └──────────────┘ ├── Policy Engine ├── Audit Logger └── Approval Workflows ``` No infrastructure changes. No rewrites. One config file. --- ## Quickstart **Step 1 — Initialize** Run this inside your project (where your `claude_desktop_config.json` exists): ```bash npx @getcordon/cli init ``` This reads your existing Claude Desktop MCP config, generates `cordon.config.ts`, and patches Claude Desktop to route all tool calls through Cordon. **Step 2 — Start** ```bash npx @getcordon/cli start ``` Cordon starts, connects to your MCP servers, and begins intercepting tool calls. Restart Claude Desktop and every tool call now flows through the gateway. ### Manual setup If you prefer to configure manually, install globally and create a config: ```bash npm install -g @getcordon/cli cordon init ``` `cordon init` generates a `cordon.config.ts`: ```typescript import { defineConfig } from '@getcordon/policy'; export default defineConfig({ servers: [ { name: 'database', transport: 'stdio', command: 'npx', args: ['-y', '@my-org/db-mcp-server'], policy: 'read-only', // Block all write operations }, { name: 'github', transport: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'], policy: 'approve-writes', // Reads pass; writes require approval tools: { delete_branch: 'block', // Never, regardless of approval }, }, ], audit: { enabled: true, output: 'stdout', // or 'file' }, approvals: { channel: 'terminal', timeoutMs: 60_000, // auto-deny after 60s; the request is retained // and replayable if approved late }, }); ``` --- ## Why Cordon | Without Cordon | With Cordon | |---|---| | Agent has unrestricted tool access | Granular per-tool policies | | No visibility into what agents did | Structured audit trail of every call | | "Did the agent just drop a table?" | Real-time terminal approvals | | Reads and writes treated the same | `approve-writes` lets reads through automatically | | Compliance team says no to AI | Audit logs ready for export | --- ## Features ### Policy Engine Define rules per tool, per server, or globally. Tool-level policies override server policies. ```typescript // Server-level default policy: 'approve-writes', // Per-tool overrides tools: { query: 'allow', // reads: pass through execute: 'approve', // writes: pause for human approval drop_table: 'block', // catastrophic: always reject list_tables: 'log-only', // audit but don't interrupt }, ``` ### Human-in-the-Loop Approvals When a tool call requires approval, Cordon pauses the agent and prompts you directly in your terminal: ``` ╔══════════════════════════════════════╗ ║ ⚠ APPROVAL REQUIRED ║ ╚══════════════════════════════════════╝ Server : database Tool : execute_sql Args : { "query": "DELETE FROM sessions WHERE expires_at < NOW()" } [A]pprove [D]eny > ``` The agent waits. You decide. Prefer Slack? Connect your workspace once with **Add to Slack** in the dashboard — no bot token to create or paste — then set `approvals: { channel: 'slack' }`. A flagged call posts an Approve / Deny card to your channel and pauses until a human clicks, and the approver's name is written onto the audit record. See the [Slack approvals setup](https://github.com/marras0914/cordon/blob/HEAD/docs/slack-approvals-setup.md). **When nobody answers in time.** The call is denied and the agent moves on, but the request isn't lost. Cordon retains the pending approval with its full context, and the dashboard lists it under **What changed → Timed-out approvals**. If someone approves the card after it expired, that late decision is recorded and the call can be re-run: ```bash cordon replay ``` The replay executes the tool and logs the outcome to the same audit stream with reason `replay of late-approved call`. It recovers the **tool call, not the agent's session** — the agent that asked is long gone. Only a call approved *after* timing out is replayable, since replaying a call that already ran would double-execute it. ### Audit Logging Every tool call is logged as structured JSON — the request, the policy decision, the response, and timing. Pipe to stdout or write to a file for your compliance team. ```json {"event":"tool_call_received","callId":"...","serverName":"database","toolName":"execute_sql","timestamp":1773434469641} {"event":"approval_requested","callId":"...","serverName":"database","toolName":"execute_sql","timestamp":1773434469641} {"event":"tool_call_approved","callId":"...","serverName":"database","toolName":"execute_sql","timestamp":1773434471203} {"event":"tool_call_completed","callId":"...","durationMs":34,"isError":false,"timestamp":1773434471237} ``` ### Read-Only Mode One policy setting to block all write operations across a server. Zero guesswork about what counts as a write — Cordon detects it from the tool name. ```typescript policy: 'read-only' // any tool starting with write/create/update/delete/drop/execute/... is blocked ``` ### Hidden Tools For tools the model should never even see — not just rejected on call, but filtered from the `tools/list` response entirely. Closes a prompt-injection surface: if the model never knows a tool exists, it can't be tricked into calling it. ```typescript { name: 'database', policy: 'approve-writes', tools: { drop_table: 'block', // call attempts are rejected internal_admin: 'hidden', // not advertised to the client at all }, } ``` ### SQL-Aware Policies For database MCP servers where a single tool takes arbitrary SQL (Postgres, SQLite, BigQuery, etc.), tool-name heuristics aren't precise enough — the name `query` doesn't tell you whether the agent's about to `SELECT` or `DROP TABLE`. Cordon ships two policies that parse the SQL itself and decide based on the statement type. ```typescript tools: { // Allow SELECTs (including CTEs that wrap a SELECT). Block everything else. query: 'sql-read-only', // Reads pass; writes (INSERT/UPDATE/DELETE/DROP/ALTER/...) pause for human approval. execute: 'sql-approve-writes', // When the tool takes SQL in a different arg name: run: { action: 'sql-read-only', sqlArg: 'statement' }, } ``` Both policies use the PostgreSQL dialect by default (others coming later) and are fail-closed: unparseable SQL is blocked rather than allowed. Prompt-injection patterns like `SELECT 1; DROP TABLE users;` and block-comment-wrapped keywords are correctly classified as writes by the AST parser. ### Closed-World Tool Catalogs Declare the exact tool surface your upstream server is expected to advertise. When the upstream adds a new tool in a future release, Cordon blocks it automatically until you explicitly promote it. ```typescript { name: 'postgres', command: 'npx', args: ['-y', '@modelcontextprotocol/server-postgres', process.env.POSTGRES_URL!], policy: 'read-only', knownTools: ['query', 'list_tables', 'describe_table'], // your approved surface onUnknownTool: 'block', // default when knownTools is set } ``` If the next Postgres MCP release adds `truncate_table`, Cordon blocks it with a stderr warning — no policy update needed. Leave `knownTools` undefined for backwards-compatible open-world behavior. ### Per-Agent Policies + Call-Graph Constraints ![Tier 1 demo — read_data succeeds, write_file blocked by call-graph rule](https://raw.githubusercontent.com/marras0914/cordon/HEAD/docs/assets/tier1-call-graph-demo.gif) Per-tool policies catch dangerous *individual* calls. Call-graph rules catch dangerous *sequences* — combinations of allowed tools used in unintended order. The classic example: an agent reads sensitive data with `read_data` (allowed) and then writes it to disk with `write_file` (also allowed). Each call is fine in isolation. The *sequence* is the problem. Cordon's call-graph rules apply on top of your per-tool policy and are **additive** — they can only raise severity, never lower it. ```typescript export default defineConfig({ // Optional identity for this Cordon process. Surfaced in audit logs. agentId: 'et-acquisition-agent', servers: [{ name: 'demo-db', transport: 'stdio', command: 'npx', args: ['-y', '@my-org/db-mcp'], policy: 'approve-writes', }], callGraph: [ // Reading data and then writing to disk is the exfil shape — block it, // even though write_file would only require approval on its own. { from: 'read_data', to: 'write_file', action: 'block', reason: 'No file writes after database reads.' }, // Glob matching: any send_* tool right after a database read needs human approval. { from: 'read_data', to: 'send_*', action: 'approve' }, // `*` matches anything: after a privileged read, every next call must be approved. { from: 'sensitive_read', to: '*', action: 'approve' }, ], }); ``` **How rules combine with per-tool policies (additive severity):** Severity ordering: `allow` < `approve` < `block`. A call-graph rule only takes effect if its action is *higher* severity than the per-tool decision. That means: - A rule with `action: 'block'` overrides an `allow` per-tool policy ✓ - A rule with `action: 'approve'` overrides `allow`, but **doesn't** lower a `block` ✓ - A rule with `action: 'allow'` never weakens a stricter base — it's a no-op - When multiple rules match, the highest-severity one wins (config order doesn't matter) One-way ratchet — tighten only, never loosen. **Audit log gains chain context.** Every `tool_call_received` event now carries `previousTool` (what was last successfully executed). Blocked / approval-required events also include `callGraphRule: { from, to }` when a rule fired: ```json {"event":"tool_call_received","toolName":"write_file","previousTool":"read_data","..."} {"event":"tool_call_blocked","toolName":"write_file","reason":"No file writes after database reads.","previousTool":"read_data","callGraphRule":{"from":"read_data","to":"write_file"},"..."} ``` **v1 scoping (read this if you're shipping per-agent policies in production):** In stdio mode (and in the current single-tenant HTTP mode), one Cordon process serves one agent identity — so `agentId` in config identifies *this deployment*, not a per-call runtime identity. The multi-tenant HTTP gateway (where one Cordon instance hosts many agents with distinct policies) is still queued — `agentId` will gain an HTTP-header source then, no config rewrite needed. `lastTool` advances **only on a clean upstream return**. Blocked, denied, and transport-failed calls don't advance the chain. v1 doesn't catch probing — an adversary that attempts `fs:delete` (blocked) and then `http:post` will see `http:post` evaluated against whatever came before the probe, not the probe itself. We chose this on purpose: tracking every blocked attempt false-positives too aggressively on legitimate flows that get blocked once and continue. Revisit when there's real adversarial-misuse data. --- ## How It Works Cordon runs as a single **aggregating MCP proxy**. Instead of Claude Desktop connecting directly to your MCP servers, it connects to Cordon. Cordon then manages your servers internally. ``` Before: Claude ──▶ MCP Server A (full access) Claude ──▶ MCP Server B (full access) After: Claude ──▶ Cordon ──▶ MCP Server A (governed) ──▶ MCP Server B (governed) ``` Your LLM client and MCP servers don't change at all. `cordon init` handles the config patching. ### HTTP Transport (n8n and other HTTP-speaking MCP clients) For clients that talk MCP over HTTP — n8n's MCP Client Tool node, hosted agents that can't spawn child processes, anything else that wants a network endpoint — Cordon can run as an HTTP listener instead of stdio. ```bash export CORDON_GATEWAY_TOKEN=your-secret-token npx @getcordon/cli start --http --port 7777 # [cordon] HTTP gateway listening on http://127.0.0.1:7777/mcp ``` Or set it in your config: ```typescript import { defineConfig } from '@getcordon/policy'; export default defineConfig({ servers: [ /* your upstream MCP servers */ ], gateway: { transport: 'http', authToken: process.env.CORDON_GATEWAY_TOKEN!, port: 7777, host: '127.0.0.1', // localhost-only by default; set to '0.0.0.0' to expose externally }, }); ``` Clients connect to `http://your-host:7777/mcp` with an `Authorization: Bearer ` header. The transport implements the [MCP Streamable HTTP spec](https://modelcontextprotocol.io/) — one endpoint serves both SSE response streams and direct JSON responses, with session multiplexing handled by session IDs in headers. All policy enforcement, audit logging, and approval workflows work identically across transports — only the wire protocol changes. **Connecting from n8n.** Point the MCP Client Tool node at your Cordon URL with the Bearer token as the credential. The deprecated SSE-only endpoint shape (older n8n versions on the legacy MCP SSE spec) is not implemented — Cordon ships only the current Streamable HTTP transport, which n8n is migrating to. **Single-tenant.** The current HTTP transport is single-tenant: all sessions share the same upstream MCP servers, policy config, and auth token. A multi-tenant hosted gateway (per-call `agentId` from headers, per-tenant policy) is on the roadmap. --- ## Configuration ### Policy actions | Policy | Behavior | |---|---| | `allow` | Pass through immediately | | `block` | Reject — agent receives an error | | `approve` | Pause pending human approval in terminal | | `approve-writes` | Reads pass through; writes require approval | | `read-only` | All write operations are blocked | | `log-only` | Pass through but flagged in the audit log | | `hidden` | Filtered from tools/list — the model never sees it | | `sql-read-only` | Parse the SQL arg, allow SELECT/WITH-SELECT, block everything else (fail-closed on unparseable) | | `sql-approve-writes` | Parse the SQL arg, allow reads, pause writes for human approval, block unparseable | Policies can be set at the server level (default for all tools) or per-tool (overrides the server default): ```typescript { name: 'my-server', policy: 'approve-writes', // server default tools: { safe_read: 'allow', // override: always allow nuke_db: 'block', // override: always block }, } ``` ### Approval channels | Channel | Status | |---|---| | `terminal` | Available — interactive prompt in your terminal | | `slack` | Available — one-click **Add to Slack** (OAuth), server-posted Block Kit cards, HMAC-verified interactions, approver captured on the record | | `web` | Coming in v0.3 | | `webhook` | Coming in v0.3 | ### Audit outputs | Output | Status | |---|---| | `stdout` | Available | | `file` | Available — JSON lines written to a local file | | `hosted` | Available — ships events to the Cordon dashboard | | `otlp` | Coming in v0.3 | --- ## Packages | Package | Description | |---|---| | `@getcordon/cli` | The CLI — `npx @getcordon/cli start` | | `@getcordon/policy` | TypeScript config SDK — `defineConfig()` and all types | | `@getcordon/core` | Core proxy engine — policy evaluator, audit logger, approval manager | --- ## Roadmap - [x] MCP proxy with aggregator model (multiple servers, one gateway) - [x] Policy engine — allow, block, approve, approve-writes, read-only, log-only, hidden - [x] Closed-world tool catalogs — `knownTools` + `onUnknownTool` for future-proof upstream surface control - [x] SQL-aware policies — `sql-read-only` / `sql-approve-writes` parse SQL arguments at call time (PostgreSQL dialect) - [x] Terminal approval channel with TTY-safe prompt - [x] Slack approval channel — Block Kit messages, polls for response - [x] Structured JSON audit logging to stdout, file, or hosted dashboard - [x] `cordon init` — auto-reads Claude Desktop config and patches it - [x] Rate limiting — sliding window, global / per-server / per-tool - [x] Hosted dashboard — audit log history, CSV/JSON export, GitHub OAuth, free for individuals - [x] Per-agent policies + call-graph constraints — sequence-aware blocking with additive severity - [x] HTTP/Streamable HTTP transport — single-tenant gateway for n8n and HTTP-speaking MCP clients - [x] Drift detection — "what changed about how your agents behave this week" in the dashboard - [x] Suggested policies — analyzes your audit history and proposes call-graph rules and gates - [x] Durable approvals — timed-out approvals are retained, surfaced, and replayable via `cordon replay` - [ ] Multi-tenant HTTP gateway — many agents on one Cordon instance with per-call `agentId` from headers - [ ] OpenTelemetry export - [ ] Team accounts and centralized governance --- ## Examples See [`examples/security-showcase`](https://github.com/marras0914/cordon/blob/HEAD/examples/security-showcase/) for a working demo of Cordon intercepting an agent that attempts to drop a production database table. ```bash cd examples/security-showcase npm install npm run demo ``` --- ## Use Cases **Enterprise** — Centralized governance across all AI agent deployments. Policy-as-code, structured logs, and a clear path to SOC2-ready audit trails. **Startup Team** — Deploy agents with confidence. Every tool call is logged, writes require approval, and your compliance team has a trail. **Solo Developer** — Secure your local Claude/Cursor setup. See exactly what your agent is calling and block anything dangerous before it reaches production. --- ## Works great with - **[Agent Toolbelt](https://www.npmjs.com/package/agent-toolbelt)** — a typed toolkit of ready-made MCP tools (web search, fetch, filesystem, and more). Wire it into Claude Desktop, then route those tool calls through Cordon for policy enforcement and audit logging. Agent Toolbelt gives your agents power; Cordon makes sure they ask before using it. - **[Build & Ship MCP Tools](https://build-mcp-tools.vercel.app/)** — the companion course that walks through building your own MCP servers end to end. 7 modules, 33 lessons; Module 0 is free, Module 6 covers securing your server with Cordon. --- ## Contributing Cordon is open source and we welcome contributions. ```bash git clone https://github.com/marras0914/cordon.git cd cordon npm install npm run build npm run dev ``` --- ## License MIT — see [LICENSE](https://github.com/marras0914/cordon/blob/HEAD/LICENSE) for details. ---

Stop trusting. Start governing.
⭐ Star on GitHub