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

Policy engine	ALLOW/DENY rules with condition trees. DENY always wins — it cannot be overridden by a later ALLOW
Conditions	Two modes: SIMPLE (flat array) and ADVANCED (nested AND/OR expression trees)
MCP proxy	Multi-transport: HTTP, STDIO, WebSocket, SSE
Audit log	Every tool call, policy change, auth event, and admin action, with before/after snapshots
Multi-tenancy	Organizations → workspaces → members, scoped at the query layer
Approvals	Flag tools as sensitive; calls block pending human approval
Credentials	AES-256-GCM encryption at rest for upstream server credentials
Admin MCP server	40 tools so an agent can administer Sentinel itself
A2A proxy	Agent-to-Agent protocol support
Web UI	Full admin and user console

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:

Service	URL
Web console	http://localhost:5173
Docs site	http://localhost:5174
API	http://localhost:3000
MCP proxy	http://localhost:3001
Admin MCP	http://localhost:3003

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.

Package	Lines	What it does
api	~72k	tRPC API — services, routers, policy evaluation, audit
web	~73k	React admin + user console
docs	~11k	Documentation site
shared	~6k	Shared types, condition evaluation, admin tool defs
mcp	~4.7k	MCP proxy server (HTTP, STDIO, WebSocket, SSE)
db	~3.3k	Prisma schema — 67 models
a2a	~2.5k	Agent-to-Agent protocol proxy
mcp-admin	~1.7k	Admin MCP server (40 tools)

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.