SentinelMCP

A reliability, safety, security, and observability control plane for AI-agent tool execution.

SentinelMCP is an open-source infrastructure project for mediating calls from AI agents to external tools. It is designed to make tool execution explicit, policy-controlled, observable, replayable, and resilient to dependency failures.

Project status: Version 0.1.1 is a public alpha. SentinelMCP can durably register exact immutable tool versions in PostgreSQL and execute authenticated, authorized reads through synthetic or HTTP adapters behind FastAPI. Mutations use durable preview, single-use confirmation, and idempotency state. Reads support request-wide deadlines, bounded retries, process-local rate limiting, retry budgets, and three-state circuit breaking. This is not production-ready software.

Verified evidence

• 617 tests passed with 95.64% branch-aware coverage in the complete Windows/Python 3.12 and PostgreSQL 17.11 gate.

• 23/23 deterministic fault scenarios matched expected attribution and dispatch behavior.

• The documented local benchmark measured the core executor at 5,051 requests/s and 0.251 ms p95 at concurrency 1 after profile-guided schema-validator caching.

These numbers and their limits are sourced in Resume evidence. The benchmark is synthetic local evidence, not a production throughput or SLO claim.

Read the portfolio case study for a concise walkthrough of the architecture, engineering decisions, measured evidence, and limitations.

Related MCP server: MCP Tool Manager

Why this exists

Agent frameworks make it easy to invoke a function. Production systems must answer harder questions: Who authorized the call? Was it a read or a mutation? Can it be retried? Did the upstream return valid data? How do we prevent a stale confirmation from changing different arguments? What failed, and can the request be reproduced safely?

SentinelMCP provides one execution path where those concerns can be enforced consistently. It does not decide what an agent should think. It controls what an agent is allowed to do.

Execution architecture

flowchart LR
    A[Agent / MCP client] --> G[MCP or REST authentication]
    G --> C[Exact versioned contract]
    C --> IV[Input validation]
    IV --> AZ[Authorization]
    AZ --> M[Mutation safety]
    M --> I[Durable idempotency]
    I --> R[Reliability controls]
    R --> T[Tool adapter]
    T --> OV[Output validation]
    OV --> E[Audit / metrics / traces]
    C --> P[(PostgreSQL)]
    M --> P
    I --> P
    E --> P

Read calls bypass the mutation-only confirmation and idempotency stages. PostgreSQL owns durable contracts, mutation state, and audit evidence; runtime bindings and reliability coordination are currently process-local.

The gateway begins as a modular monolith. Protocol adapters share one application orchestrator, while registry, policy, mutation safety, execution, audit, and telemetry remain separate modules with explicit ownership. This avoids distributed transactions inside the control plane before scale requires service extraction.

See Architecture and Design decisions for the detailed request lifecycle and tradeoffs.

Start with the Quickstart and verified examples.

Implemented capabilities

• Typed namespaces, names, exact SemVer versions, identities, and tool references

• Deeply immutable tool definitions with read or mutation operation classes

• RFC 8785 canonical definition bytes and deterministic SHA-256 fingerprints

• Draft 2020-12 input/output schema checks with bounded complexity and no remote references

• Structured runtime argument and output validation errors

• Persistence-independent registry protocol and thread-safe in-memory implementation

• Migration-managed PostgreSQL registry with transactional immutable registration

• Real PostgreSQL concurrency, restart-persistence, migration, and corruption checks

• Exact lookup, deterministic listing, SemVer ordering, and latest-version resolution

• Idempotent identical registration and immutable conflict rejection

• Immutable execution requests, contexts, structured successes, and structured failures

• Exact-version runtime bindings kept separate from semantic tool definitions

• Deterministic synthetic tools and a single-attempt bounded HTTP adapter

• HTTPS-by-default outbound policy with exact host allowlists, public-address enforcement, all-answer DNS validation, redirect refusal, and per-request IP pinning with preserved TLS SNI

• Status-first upstream classification, safe JSON decoding, and output-schema enforcement

• Minimal POST /v1/execute FastAPI gateway with stable success and error envelopes

• Declared and streamed REST request-body limits enforced before JSON decoding

• Bounded signed-JWT verification with explicit key IDs, algorithm allowlist, issuer, audience, signature, and time validation

• Immutable normalized principals and required default-deny authorization before dispatch

• Exact tool-identity and read/mutation policy with role/scope conditions and deny precedence

• PostgreSQL-backed mutation preview with hashed, expiring, exact-request-bound confirmations

• Atomic single-use challenge consumption and durable scoped idempotency records

• Terminal outcome recovery, conflict detection, fail-closed storage behavior, and real 32-client race tests

• Request-wide monotonic deadlines with cancellation of overdue adapter attempts

• Read-only transient retries with capped exponential full jitter and aggregate retry budgets

• Thread-safe token-bucket admission and generation-safe three-state circuit breaking

• Stable local-rate-limit, circuit-open, and deadline-exhausted transport errors

• Versioned payload-free audit events with append-oriented PostgreSQL persistence and deterministic request/execution lookup

• Mutation pre-dispatch audit intent with fail-closed behavior and honest post-dispatch unknown outcomes

• OpenTelemetry API lifecycle spans, bounded structured JSON logs, and low-cardinality Prometheus metrics exposed through an optional /metrics endpoint

• Provisioned local Prometheus and Grafana configuration with a signal-focused dashboard

• Versioned bounded replay records with strict local append-only persistence and drift detection

• Synthetic-only replay by default with current reauthorization, pre-dispatch audit, dry run, and a final binding guard against target replacement

• JSON-emitting sentinel commands for tool discovery, execution, record inspection, replay, evaluation smoke checks, and bounded diagnostic benchmarks

• Official MCP Python SDK v2 discovery and invocation over the same registry, executor, authorization, reliability, audit, and telemetry lifecycle as REST

• Reversible exact-version MCP names, trusted in-memory/stdio principal injection, authenticated Streamable HTTP composition, and PostgreSQL-backed MCP mutation preview/confirmation

• Versioned deterministic fault scenarios for HTTP status, body, transport, retry, policy, duplicate-mutation, and ambiguous-mutation behavior

• Machine-readable evaluation artifacts with expected/observed error, attribution, dispatch count, labels, and per-scenario timing

• Reproducible profile-first benchmarks with raw per-request samples, CPU and Windows working-set evidence, authenticated REST, official MCP SDK, audit/telemetry, failure, and PostgreSQL paths

The full behavioral contract and current limits are in Tool registry and schemas and Execution lifecycle. Durable storage is documented in PostgreSQL persistence, and the security boundary is documented in Security model. Mutation delivery limits are documented in Mutation safety. Reliability controls defines the retry matrix and deployment limits. Audit contract and Observability define the evidence, telemetry, redaction, and failure policies. Safe replay and the CLI reference document operator workflows and their security limits. API reference and Configuration document the public adapters and explicit composition controls. MCP integration documents discovery, exact-version encoding, transports, authentication assumptions, mutation actions, errors, and cancellation. Reliability evaluation defines the Phase 11 scenario and attribution contract. Benchmarks defines the Phase 12 methodology, evidence, and limits.

CLI quick start

sentinel tools list
sentinel execute demo.math.add@1.0.0 --arguments '{"a":2,"b":3}' --record
sentinel inspect RECORD_ID
sentinel replay RECORD_ID --dry-run
sentinel replay RECORD_ID
sentinel eval run --output phase11-evaluation.json
sentinel benchmark suite --output benchmark-results/local

Replay defaults to the local .sentinelmcp/replays directory and only dispatches to explicitly marked synthetic read tools after current authorization and audit checks.

Repository map

src/sentinelmcp/
  adapters/          MCP and REST transport boundaries
  application/       Tool-call orchestration use cases
  domain/            Transport- and storage-independent types and errors
  registry/          Tool definitions, versions, and execution policies
  policy/            Authentication context and authorization decisions
  mutation_guard/    Preview, confirmation, replay protection, idempotency
  execution/         Runtime bindings, adapter protocol, bounded upstream normalization
  audit/             Redaction and append-only audit events
  telemetry/         Traces, metrics, and structured logging
  replay/            Safe reconstruction against synthetic services
  evaluation/        Scenario execution and reliability attribution
  fault_injection/   Controlled failure plans for test environments
  cli/               Developer and operator commands
services/mock_tools/ Synthetic APIs used by demos and tests
tests/                Unit, architecture, API, integration, concurrency, property tests
deploy/               Local infrastructure and observability configuration
benchmarks/           Reproducible load generation and result processing
scenarios/            Deterministic demo and evaluation fixtures

Development setup

SentinelMCP requires Python 3.12 or newer.

python -m venv .venv
source .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Run the quality gates:

ruff format --check .
ruff check .
mypy
pytest

The complete suite needs PostgreSQL 17. Start the pinned local service, load the development test URL from .env.example, and apply migrations before pytest:

docker compose up -d postgres
export SENTINELMCP_DATABASE_URL='postgresql+psycopg://sentinelmcp_test:sentinelmcp_dev_only@localhost:54329/sentinelmcp_test'
export SENTINELMCP_TEST_DATABASE_URL="$SENTINELMCP_DATABASE_URL"
python -m alembic upgrade head
pytest

Implementation roadmap

Work is intentionally incremental. Each phase has tests and exit criteria before the next phase begins. The complete plan is in Implementation plan.

Benchmarks

On the recorded Windows/Python 3.12 host, the optimized core executor measured 5,051 requests/s with 0.251 ms p95 latency at concurrency 1; authenticated in-process REST measured 1,041 requests/s with 1.160 ms p95. These are local synthetic measurements, not production capacity or service-level claims. The benchmark report defines the workloads and limits, and the committed result set contains the manifest, profile, raw samples, and complete generated summary.

Security

This project is not yet ready for production use. Read the Threat model and Security policy before experimenting with sensitive data. Synthetic services and non-secret fixtures are the only supported test targets during development.

License

Licensed under the Apache License 2.0. See LICENSE.