mizcausevic-dev/mcp-sentinel

Purpose and principal workflow

MCP Sentinel is a Node.js/Express API for evaluating MCP server registrations, tool schemas, and tool invocations against governance and security checks, then exposing fleet posture and audit views. The documented main trigger is an agent or assistant making a tool call: it submits an invocation to the API, which validates the payload, scores prompt-injection and PII risk, and returns a decision. Platform teams and operators also submit registration and schema checks and read fleet views. The sampled implementation uses seeded in-memory data; it does not establish persistent storage or live polling.

Components

API and request boundary

• Agent or assistant — *External; path: null.* The README identifies an agent or assistant initiating a tool call and describes invocation validation as an inflight check.

• Express API application — src/index.ts. Creates the Express app, installs middleware, mounts route groups, serves health and Swagger endpoints, and listens when run as the main module.

• Validation request contracts — src/schemas/validation-schemas.ts. Zod schemas define and parse the registration, tool-schema, invocation, and security-scan request shapes used by the validation routes.

• Governance validation routes — src/routes/validate.ts. Exposes the validation endpoints, rejects invalid payloads, dispatches supported checks, and combines registration validation into a posture-check response.

• API documentation — src/docs/swagger.ts. The application mounts its OpenAPI specification at /docs; the spec’s contents were not sampled.

Governance evaluation

• Registration posture evaluator — src/governance/server-validator.ts. Scores authentication, OAuth scopes, tool capabilities, transport, and ownership, returning a status, findings, and recommended action.

• Schema-drift evaluator — src/governance/schema-drift.ts. The README describes comparing tool schemas with baselines for added or removed parameters and risk-flag or signature changes; source behavior was not sampled.

• Invocation risk evaluator — src/governance/injection-detector.ts. Scans invocation context, arguments, and result preview for injection and PII/credential signatures, adds latency risk, and returns a threshold-based verdict.

• Combined security scanner — src/governance/security-scan.ts. The README documents combined security scanning, and the route calls this module; its checks and internal flow were not sampled.

• Policy lookup — src/governance/policy-engine.ts. Lists and finds policies from the audit-data module; the sampled file does not show it participating in validation decisions.

Fleet visibility and state

• Server route surface — src/routes/servers.ts. The tree and README document server listing, individual server, and tool endpoints; route implementation was not sampled.

• Audit, incident, policy, and dashboard routes — src/routes/audits.ts. Serves audit, incident, and policy lists and computes a dashboard summary from fleet, audit, incident, and policy data.

• Seeded server registry — src/data/servers.ts. Defines server records and an in-memory registry, with a lookup helper.

• Seeded governance records — src/data/audits.ts. Defines in-memory audit, incident, and policy records; the samples are static data rather than evidence of runtime persistence.

Runtime configuration

• Environment settings — src/config/env.ts. Loads environment variables and provides defaults for the port, runtime mode, thresholds, polling intervals, and alert webhook URL; sampled code uses the mode, port, and injection threshold.

Relationships

• Agent or assistant -> Express API application: initiates an MCP tool-call validation request; the README names the actor and the API’s validation role.

• Express API application -> Governance validation routes: mounts the validation, security-scan, and posture-check route groups; the application wiring establishes this dispatch.

• Governance validation routes -> Validation request contracts: parses request bodies with the relevant Zod schemas and returns a 400 response for invalid payloads.

• Governance validation routes -> Registration posture evaluator: calls registration evaluation for server validation and posture checks; the result is mapped to the combined posture status.

• Governance validation routes -> Schema-drift evaluator: dispatches parsed schema-check requests for evaluation; the route call is sampled, while evaluator details are not.

• Governance validation routes -> Invocation risk evaluator: dispatches parsed invocation requests and returns the verdict; the evaluator reads the configured injection threshold.

• Governance validation routes -> Combined security scanner: dispatches parsed security-scan requests; scanner internals are not established.

• Express API application -> API documentation: mounts the OpenAPI specification in Swagger UI at /docs.

• Express API application -> Server route surface: mounts the server router under /api/servers; endpoint behavior is documented, but route implementation was not sampled.

• Express API application -> Audit, incident, policy, and dashboard routes: mounts these routes under their API prefixes.

• Audit, incident, policy, and dashboard routes -> Seeded server registry: reads server records to calculate fleet counts and average posture in the dashboard summary.

• Audit, incident, policy, and dashboard routes -> Seeded governance records: reads audit, incident, and policy arrays for list responses and dashboard totals.

• Policy lookup -> Seeded governance records: reads the policy array to list or find a policy.

• Express API application -> Environment settings: reads the port and runtime mode for startup, health output, and middleware configuration.

Coverage limits

The supplied source sample omits implementations for schema-drift evaluation, security scanning, server routes, and the OpenAPI specification. The README describes their intended behavior, but their detailed checks and runtime wiring beyond the sampled route calls or mounts could not be established. The excerpt also does not show persistence, ingestion/polling workers, or alert delivery.