mcp-reliable

Runtime observability and reliability for the Model Context Protocol
ecosystem. Where tools like mcp-observatory audit servers before
deployment and inspector helps you debug one by hand, mcp-reliable
watches servers while they're running: is this server up right now, is a
given tool getting slower or less reliable over time, and did its schema or
output shape just change out from under the agents calling it.

Live on npm, verified with a real standalone install — not just a
local monorepo checkout — as
mcp-reliable plus six
scoped libraries under
@mattral:
@mattral/core,
@mattral/storage,
@mattral/collector,
@mattral/notifier,
@mattral/agent-interface,
and @mattral/server.
See docs/decisions/0013-npm-scope-rename.md
for why @mattral and not a dedicated @mcp-reliable org.

Full design rationale lives in docs/ — start with
docs/architecture.md if you want the "how" and
docs/roadmap.md for exactly what's implemented vs.
planned. This README is the fast path to running it.

What's actually here today

• Health checks — connect to a server, confirm it's reachable, list its
  tools, detect schema changes. Never calls a tool (see
  why).
• A traffic-observing proxy — wrap a real stdio MCP server with one
  command-line change and get real per-call latency, success/failure, and
  output-shape drift detection, with zero changes to the server itself.
• A CLI (mcp-reliable) — init, add-server, remove-server,
  servers, monitor, report, proxy. See
  docs/cli-reference.md.
• A REST API — everything above, queryable over HTTP, redacting secrets
  from any transport config it returns. See
  docs/api-reference.md.
• A web dashboard — a fleet overview and per-server detail page (health
  history, tool breakdown, drift/alerts, execution log), served as static
  assets by the same REST API process. See
  docs/dashboard-design.md.
• Webhook and Slack alerting — monitor and proxy both open/resolve
  alerts (unreachable, health degradation, drift) and deliver them via
  --webhook/--slack-webhook. See
  docs/decisions/0010-alerting-notifier-design.md.
• An agent-facing MCP interface — mcp-reliable mcp exposes health,
  drift, alerts, and a synthesized should-I-use-this recommendation as MCP
  tools, so an agent can query mcp-reliable directly. See
  docs/decisions/0011-agent-interface-design.md.
• SQLite storage, zero config, one file per project.

Not yet built: SSE/HTTP support in the traffic-observing proxy (and the
agent interface, which is also stdio-only for now), statistical drift
detection, token tracking, and the rest of P2 in
docs/roadmap.md.

Quick start

npm install -g mcp-reliable
mcp-reliable init
mcp-reliable add-server --name my-server --stdio -- npx my-mcp-server
mcp-reliable monitor --server my-server --once

Then walk through docs/getting-started.md
for the full loop (health checks, the traffic-observing proxy, drift
detection, alerting, the dashboard, and the agent-facing MCP interface),
using the bundled examples/reference-mcp-server so there's nothing
external to stand up first.

Building from source (for contributing, or trying pre-release changes)

Requires Node.js 20+.

git clone https://github.com/Mattral/mcp-reliable.git
cd mcp-reliable
npm install
npm run build
npm test   # 256 tests, none of them mocked at the protocol level — see docs/testing.md

node packages/cli/dist/index.js init
node packages/cli/dist/index.js add-server \
  --name reference --stdio -- node examples/reference-mcp-server/dist/index.js
node packages/cli/dist/index.js monitor --server reference --once

npm link inside packages/cli to get a local mcp-reliable command
without a real install.

Project layout

packages/core        pure data model, health scoring, drift detection (no I/O)
packages/storage      SQLite persistence behind a storage-agnostic interface
packages/collector    health checks + the traffic-observing stdio proxy
packages/notifier     webhook and Slack alert delivery
packages/agent-interface   agent-facing MCP tools (health, drift, alerts, recommendations)
packages/cli          the mcp-reliable command-line tool
packages/server       REST API over stored data, serves the built dashboard
packages/dashboard    React + Tailwind web dashboard (fleet overview + server detail)
examples/             a tiny reference MCP server used by tests and the getting-started guide
docs/                 architecture, data model, CLI/API reference, ADRs, roadmap

Contributing

See CONTRIBUTING.md. Short version: npm run lint && npm run build && npm test should all be clean before opening a PR, and any
change to core's algorithms should come with a test that would have
caught the bug if you'd gotten it wrong — see
docs/decisions/0005-health-score-formula.md
for a real example of exactly that happening during this project's own
development.

Releasing

See PUBLISHING.md for the mechanical checklist
(npm publish order, tagging, GitHub release) and
RELEASE_NOTES_v1.0.0.md for what shipped in
the current release.

License

MIT — see LICENSE.