Open-Source Systems Project
SentinelMCP
Reliability, safety, security, and observability control plane for AI-agent tool execution.
SentinelMCP mediates REST and official MCP calls through one transport-independent execution lifecycle. It is a personal open-source systems project and is not connected to, derived from, or deployed at an employer.
01
Problem
AI agents can turn a model decision into a real tool call, but the protocol boundary alone does not provide authentication, authorization, schema stability, mutation safety, bounded retries, or durable evidence. SentinelMCP explores how those responsibilities can be composed into one explicit control plane without creating a second execution engine for each transport.
02
Architecture
REST and official MCP ingress converge on the same registry, policy, mutation, reliability, validation, audit, and telemetry services. Read calls bypass mutation-only stages.
- Agent / MCP Client
- Authentication
- Exact Versioned Contract
- Input Validation
- Authorization
- Mutation Safety
- Durable Idempotency
- Reliability Controls
- Tool Adapter
- Output Validation
- Audit / Metrics / Traces
PostgreSQL stores immutable contracts, confirmation challenges, idempotency state, and audit events. Runtime bindings, rate limits, retry budgets, and circuit state remain process-local in version 0.1.x.
03
Hard Engineering Problems
- Exact SemVer contracts and RFC 8785 fingerprints reject silent schema drift and latest-version ambiguity.
- Operational bindings are separate from immutable tool contracts, keeping endpoints and credentials out of registry identity.
- Mutation confirmation binds the principal, exact tool reference, definition fingerprint, and canonical arguments before an atomic PostgreSQL consume-and-claim transaction.
- Ambiguous post-dispatch mutation failures become durable unknown outcomes instead of unsafe automatic retries or an exactly-once claim.
- Retries are limited to classified transient read failures and consume one request-wide deadline plus a separate retry budget.
04
Security
REST authentication verifies bounded Ed25519 JWTs with an explicit algorithm allowlist, key ID, issuer, audience, expiry, issued-at, and optional not-before checks. Default-deny authorization distinguishes reads from mutations, supports role and scope conditions, and gives explicit deny precedence.
Outbound HTTP requires HTTPS by default, can enforce an exact host allowlist, validates every DNS answer, rejects non-global and transition addresses, refuses redirects, and pins the connection IP while preserving Host and TLS SNI. Public errors omit upstream bodies, database URLs, exception details, stack traces, and local paths.
05
Reliability
The executor combines request-wide deadlines, bounded full-jitter read retries, retry budgets, token-bucket admission, and a generation-safe three-state circuit breaker. Mutations require preview and confirmation; completed duplicates recover the persisted result, while conflicts and pending or unknown states never blindly redispatch.
06
Observability
Payload-free audit events persist to PostgreSQL. OpenTelemetry spans, bounded structured logs, and Prometheus metrics exclude request and response payloads while keeping metric labels finite. This separates durable operational evidence from best-effort traces, logs, and process-local metrics.
07
Replay
Replay is synthetic-read-only by default, verifies definition fingerprints, reauthorizes against current policy, records an audit event before dispatch, and performs a final binding guard. Local replay files are intentionally constrained and are not presented as encrypted or tamper-proof storage.
08
MCP Integration
The official MCP Python SDK exposes reversible exact-version tool names over the same execution services as REST. Trusted in-memory and stdio composition requires an explicit principal. Streamable HTTP bridges the same bearer authenticator and denies unconfigured callers by default.
09
Fault Evaluation
The deterministic suite verified normalized error, attribution, and dispatch behavior using injected transports. It does not measure model accuracy, production failure rates, or service levels.
10
Performance
Profile-guided work identified repeated immutable JSON Schema compilation as the dominant core cost. A bounded validator cache improved the concurrency-1 core path while preserving exact contract validation.
Local synthetic benchmark: 26,000 request samples across seven composition paths and five trials per group on Windows 11, Python 3.12.14, PostgreSQL 17.11, and a 22-logical-CPU Intel host. These measurements do not establish production capacity, external-network latency, multi-process scaling, or a service-level objective.
11
Testing
The release gate also passed Ruff formatting and lint, strict mypy across 128 files, dependency auditing, migrations, package metadata and Markdown-link checks, sdist and wheel inspection, Twine validation, and isolated installed-wheel smoke tests.
12
Tradeoffs / Limitations
- The project is a public alpha and reference control plane, not a hosted production deployment.
- Reliability coordination and runtime bindings are process-local.
- Mutation delivery is not universal exactly-once; a crash after an external effect can require operator reconciliation.
- Policy and signing keys are deployment configuration; OIDC/JWKS, revocation, tenant identity, and policy administration are not built in.
- Audit records are append-oriented but not cryptographically tamper-proof against a database administrator.