Sentinel

A self-hosted governance layer for MCP servers. Sentinel sits between your AI agents and the tools they call, evaluates every request against your policies, and writes an audit trail of what happened.

Runs entirely on your own machine. Postgres is the only hard dependency — no API keys, no cloud account, no phoning home.

agent ──▶ Sentinel proxy ──▶ policy engine ──▶ MCP server
                                   │
                                   └──▶ audit log

Why this exists

If you give an agent a set of MCP tools, you have handed it the ability to act. Most setups have no answer to three questions:

• Which tools is this agent allowed to call, under which conditions?

• What did it actually do?

• Who approved the thing that touched production?

Sentinel answers all three with a policy engine that evaluates conditions per call, an append-only audit log with before/after snapshots, and an approval workflow for anything you flag as sensitive.

What's in the box

Quick start

Requires Node 20+, pnpm, and Postgres.

git clone https://github.com/gong8/sentinel-oss.git
cd sentinel-oss
cp .env.example .env        # generate secrets, point DATABASE_URL at your Postgres
pnpm setup                  # install, generate client, push schema, seed
pnpm dev

Need a Postgres? docker compose up -d postgres starts one.

That gets you:

The seed creates an Acme Corporation org with three users and prints their access tokens. Run pnpm db:creds any time to print them again.

Point an agent at it

Add the proxy to your MCP client config:

{
  "mcpServers": {
    "sentinel": {
      "url": "http://localhost:3001/mcp",
      "headers": { "Authorization": "Bearer YOUR_ACCESS_TOKEN" }
    }
  }
}

Register upstream servers in the web console, write policies against their tools, and every call now routes through the policy engine.

Optional: agent features

Sentinel has a built-in admin agent (chat your way through configuration). It needs an LLM, and supports several providers — including fully local ones, so you never have to buy an API key:

• Ollama or any OpenAI-compatible endpoint (LM Studio, llama.cpp, vLLM) — local, free

• Anthropic, OpenAI, or Gemini — if you'd rather bring a key

Everything else in Sentinel works with no LLM configured at all.

Architecture

A pnpm + Turborepo monorepo.

Roughly 177k lines of source and 163k lines of tests across 218 test files.

The most reusable piece is packages/api/src/services/policyCondition.ts — a ~1,300-line condition tree evaluator with no dependencies beyond Zod and a logger. It knows nothing about MCP, Prisma, or Sentinel, and could be lifted into any project that needs policy expressions.

Deeper docs live in docs/ — start at docs/README.md.

Testing

pnpm test:unit          # no database needed
pnpm test:integration   # requires TEST_DATABASE_URL
pnpm test:security      # tenant isolation, DENY precedence
pnpm test:e2e           # Playwright
pnpm check              # format, lint, types, tests

Project conventions

This codebase holds itself to a few non-negotiable rules, enforced by lint config and git hooks in .claude/hooks/:

• No as type assertions (except as const), no any, no @ts-ignore, no eslint-disable

• Every database query scoped to organizationId

• All input validated with Zod

• Credentials encrypted before storage

• Sensitive actions audit logged, admin actions with before/after snapshots

• DENY policies cannot be bypassed, and that is tested explicitly

See CLAUDE.md for the full development guide.

Contributing

See CONTRIBUTING.md. Security issues: SECURITY.md.

License

GNU AGPL-3.0. If you run a modified Sentinel as a network service, you must make your modifications available to its users.