MegaMCP Sentinel

Monitoring & reliability for MCP servers. Sentinel speaks the Model Context Protocol — it runs the real lifecycle (initialize handshake → tools/list → latency → schema-drift diff) against a target MCP server, keeps history, and flags trouble. A generic HTTP ping can't tell you a server is up but broken; Sentinel can.

It ships two ways:

• a CLI (check / watch) for cron and CI, and
• an MCP server (list_targets, check_target, health_summary) — i.e. an MCP server that monitors MCP servers.

Quick start

# check a Streamable HTTP MCP endpoint with the published CLI
npx @megamcp/sentinel check https://your-server.example/mcp

# pass auth headers for private MCP endpoints
npx @megamcp/sentinel check https://your-server.example/mcp \
  --header "Authorization: Bearer $MCP_TOKEN"

# tune the one-off check for production expectations
npx @megamcp/sentinel check https://your-server.example/mcp \
  --timeout-ms 30000 --latency-budget-ms 5000 --min-tools 3

# use as a CI/release gate: exit 1 on DOWN or DEGRADED
npx @megamcp/sentinel check https://your-server.example/mcp \
  --timeout-ms 30000 --latency-budget-ms 5000 --min-tools 3 --fail-on-degraded

# save machine-readable evidence before the command exits
npx @megamcp/sentinel check https://your-server.example/mcp \
  --fail-on-degraded --output sentinel-result.json

# turn saved evidence into a customer-ready Reliability Audit report
npx @megamcp/sentinel audit sentinel-result.json --output mcp-reliability-audit.md \
  --evidence-output sanitized-sentinel-result.json \
  --customer "Jane Buyer" --company "Acme AI" --prepared-by "MegaMCP"

# create a reusable multi-target config from a production URL
npx @megamcp/sentinel init https://your-server.example/mcp \
  --id production-mcp --label "Production MCP" \
  --header "Authorization: Bearer $MCP_TOKEN"

# repo development
npm install
npm run build

# one-shot check of all targets (exits non-zero if any are DOWN)
npm run check

# continuous watch
npm run watch          # every 60s
node dist/cli.js watch 15

# generate ../web/status.json + ../web/status.html
npm run report

The repo ships with a bundled echo-sample MCP server as a live target, so npm run check works with zero external setup.

Exit codes are designed for automation:

• 0 when every selected target is up, or only degraded without --fail-on-degraded
• 1 when any selected target is down
• 1 when any selected target is degraded and --fail-on-degraded is set
• 2 for CLI usage errors

GitHub Actions release gate

Drop this into a repo that publishes or deploys an MCP server. It fails the workflow on down or degraded, keeps the raw Sentinel JSON as an artifact, and avoids writing tokens into a config file.

name: MCP protocol gate

on:
  pull_request:
  push:
    branches: [main]

jobs:
  sentinel:
    runs-on: ubuntu-latest
    steps:
      - name: Check MCP protocol health
        env:
          MCP_URL: ${{ secrets.MCP_URL }}
          MCP_TOKEN: ${{ secrets.MCP_TOKEN }}
        run: |
          set -euo pipefail
          npx --yes @megamcp/sentinel@latest check "$MCP_URL" \
            --header "Authorization: Bearer $MCP_TOKEN" \
            --timeout-ms 30000 \
            --latency-budget-ms 5000 \
            --min-tools 3 \
            --fail-on-degraded \
            --output sentinel-result.json

      - name: Upload Sentinel result
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: sentinel-result
          path: sentinel-result.json

Use MCP_URL for the Streamable HTTP endpoint that agents call. Keep MCP_TOKEN in GitHub Actions secrets, or remove the --header line for a public MCP endpoint. --output writes the JSON artifact before Sentinel exits, so failed release gates still preserve the evidence for review.

Release operators: see the npm publish runbook before dispatching the @megamcp/sentinel npm publish workflow.

What it checks (per target)

| Signal | Meaning | |---|---| | reachable / handshake | Did initialize complete? | | tools/list | Did the server return its tool catalog? | | toolCount | How many tools — below minTools = degraded | | latency | connect + list timing; over latencyBudgetMs = degraded | | schema drift | Tools added / removed / changed vs. last known-good |

Status is up · degraded · down.

Configure targets

Create sentinel.config.json from a live Streamable HTTP endpoint:

npx @megamcp/sentinel init https://your-server.example/mcp \
  --id production-mcp \
  --label "Production MCP" \
  --timeout-ms 30000 \
  --latency-budget-ms 5000 \
  --min-tools 3 \
  --header "Authorization: Bearer $MCP_TOKEN"

init writes one starter target and refuses to overwrite an existing config unless you pass --force. Use --output path/to/sentinel.config.json when you keep checks in a dedicated ops directory.

You can also edit sentinel.config.json directly. Two transports:

{ "type": "stdio", "command": "npx", "args": ["-y", "@scope/server"] }
{ "type": "http",  "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer ..." } }

See _examples in the config file for full shapes. Point SENTINEL_CONFIG=/path/to.json to use a different file.

For one-off HTTP checks, repeat --header "Name: value" on the CLI instead of writing a config file. Use --timeout-ms, --latency-budget-ms, and --min-tools on direct URL checks when a production MCP endpoint has slower startup, a stricter latency SLO, or a known minimum tool count. Add --fail-on-degraded when the check is guarding a deploy, cron alert, or release pipeline and degraded should block the run. Add --output path/to/result.json to persist machine-readable evidence even when the check exits non-zero.

Generate a Reliability Audit report

Use sentinel audit after a saved check to create the markdown handoff for a $499 MCP Reliability Audit:

npx @megamcp/sentinel check https://your-server.example/mcp \
  --fail-on-degraded --output sentinel-result.json
npx @megamcp/sentinel audit sentinel-result.json --output mcp-reliability-audit.md \
  --evidence-output sanitized-sentinel-result.json \
  --customer "Jane Buyer" \
  --company "Acme AI" \
  --prepared-by "MegaMCP" \
  --note "Scope: production MCP endpoint only"

The report includes executive summary metrics, optional engagement context, per-target reliability scores, protocol findings, prioritized fixes, scoring notes, and sanitized attachment guidance. Add --evidence-output sanitized-sentinel-result.json to create a redacted JSON evidence attachment for customer handoff; Sentinel removes bearer tokens, API keys, passwords, secret query parameters, and private URLs from report-derived evidence. It accepts both sentinel check --output arrays and npm run report status JSON files.

Architecture

config.ts ─▶ orchestrate.ts ─▶ monitor.ts ─▶ (MCP client → target)
                  │                  └─ schema fingerprint + drift
                  ▼
              state.ts (history + last-known schema, JSON in ./state)
                  │
        ┌─────────┴─────────┐
     cli.ts              server.ts   (Sentinel as an MCP server)

monitor.ts is the engine and is disk-pure; orchestrate.ts wires config → check → persist and is shared by both entry points.

Run Sentinel as an MCP server

node dist/server.js

Add to any MCP client config as a stdio server (command: node, args: [".../dist/server.js"]), then call check_target / health_summary from your agent.

Part of MegaMCP — the reliability layer for the MCP ecosystem.