Cordon

Cordon

The Security Gateway for AI Agents

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

---

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.

---

Demo

https://github.com/user-attachments/assets/153d978f-6303-443a-b49b-b4ec7ebf0452

---

The Problem

The Model Context Protocol (MCP) 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):

npx cordon-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

npx cordon-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:

npm install -g cordon-cli
cordon init

cordon init generates a cordon.config.ts:

import { defineConfig } from 'cordon-sdk';

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 if no response
  },
});

---

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.

// 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.

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.

{"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.

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.

{
  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.

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.

{
  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.

---

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.

---

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):

{
  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 — Block Kit messages, HMAC-verified interactions
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
cordon-cli	The CLI — npx cordon-cli start
cordon-sdk	TypeScript config SDK — defineConfig() and all types
@getcordon/core	Core proxy engine — policy evaluator, audit logger, approval manager

---

Roadmap

• MCP proxy with aggregator model (multiple servers, one gateway)
• Policy engine — allow, block, approve, approve-writes, read-only, log-only, hidden
• Closed-world tool catalogs — knownTools + onUnknownTool for future-proof upstream surface control
• SQL-aware policies — sql-read-only / sql-approve-writes parse SQL arguments at call time (PostgreSQL dialect)
• Terminal approval channel with TTY-safe prompt
• Slack approval channel — Block Kit messages, polls for response
• Structured JSON audit logging to stdout, file, or hosted dashboard
• cordon init — auto-reads Claude Desktop config and patches it
• Rate limiting — sliding window, global / per-server / per-tool
• Hosted dashboard — audit log history, CSV/JSON export, GitHub OAuth
• Stripe billing — Free and Pro tiers
• OpenTelemetry export
• Team accounts and centralized governance
• HTTP/SSE transport support

---

Examples

See examples/security-showcase for a working demo of Cordon intercepting an agent that attempts to drop a production database table.

cd examples/security-showcase
npm install
npm run demo

---

Use Cases

Solo Developer — Secure your local Claude/Cursor setup. See exactly what your agent is calling and block anything dangerous before it reaches production.

Startup Team — Deploy agents with confidence. Every tool call is logged, writes require approval, and your compliance team has a trail.

Enterprise — Centralized governance across all AI agent deployments. Policy-as-code, structured logs, and a clear path to SOC2-ready audit trails.

---

Works great with

• 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 — the companion course that walks through building your own MCP servers end to end. Module 6 covers securing your server with Cordon.

---

Contributing

Cordon is open source and we welcome contributions.

git clone https://github.com/marras0914/cordon.git
cd cordon
npm install
npm run build
npm run dev

---

License

MIT — see LICENSE for details.

---

Stop trusting. Start governing.
⭐ Star on GitHub