MCP Observatory

MCP Observatory

More badges

Free, open-source MCP security testing from ClearFrame. MCP Observatory is the CI-native security tool for teams shipping custom MCP servers. Test during development, catch schema drift, simulate attacks, and generate compliance evidence — before agents depend on your servers.

Also available in Simplified Chinese.

Runtime enforcement: Use mcp-seatbelt to block dangerous MCP tool calls at runtime based on observatory scan results.

Get Started

[Step-by-step setup guide](https://mcp-observatory.com/start/) · macOS, Windows, Linux · Node.js 20+ and npm (install Node.js LTS).

1. Run your first scan

Open Terminal or PowerShell in your project folder and paste:

npx -y @kryptosai/mcp-observatory@latest

This downloads Observatory and checks your first configured MCP server. With no configured server, it uses an included example. To try only that example, run npx -y @kryptosai/mcp-observatory@latest demo --example.

2. Read the result

The terminal shows the target, grade, findings, and saved receipt path. Failed checks are findings to review, not a request to pay. If connection failed, fix the startup command or credentials and rerun. A demo grade describes the example, not your own server.

3. Review locally, then continue in ClearFrame

npx -y @kryptosai/mcp-observatory@latest dashboard

npx -y @kryptosai/mcp-observatory@latest clearframe

The dashboard shows your local scan history, HTML reports, and JSON downloads. No account, upload, subscription, or time-based retention limit. Stop it with Ctrl+C.

The clearframe command writes a private instruction file and prints a read-only CLI command. Review the file, then run that command or paste it into a new ClearFrame Mac chat with your project open. It does not launch ClearFrame or upload evidence automatically.

[Get ClearFrame CLI or the Mac app](https://clearframecode.com/download/?utm_source=mcp-observatory&utm_medium=readme&utm_campaign=opensource) · Currently Apple Silicon Mac. ClearFrame has its own account and usage terms; all Observatory features work without it.

MCP Observatory is free and MIT licensed. Product telemetry is off by default and makes no telemetry network request before explicit opt-in. Use telemetry preview to inspect fields or telemetry enable to opt in. Privacy details.

npx -y @kryptosai/mcp-observatory@latest test npx -y @modelcontextprotocol/server-everything

- uses: KryptosAI/mcp-observatory/action@v1

If this repo is an MCP package, that tests npx -y . Otherwise set command:.

Or generate a full workflow: npx -y @kryptosai/mcp-observatory@latest setup-ci --all --command "npx -y my-mcp-server" --sarif

Install: npx -y @kryptosai/mcp-observatory@latest · brew tap kryptosai/mcp-observatory https://github.com/KryptosAI/mcp-observatory && brew install mcp-observatory · docker pull ghcr.io/kryptosai/mcp-observatory:latest · curl -fsSL https://raw.githubusercontent.com/KryptosAI/mcp-observatory/main/scripts/install.sh | sh

docker run --rm ghcr.io/kryptosai/mcp-observatory:latest demo

docker run --rm ghcr.io/kryptosai/mcp-observatory:latest test npx -y @modelcontextprotocol/server-everything

Scanning a server on the host needs network and, for local files, a volume mount (-v "$PWD:$PWD" -w "$PWD").

Agents: npx -y @kryptosai/mcp-observatory@latest serve

Default-deny connect: npx -y @kryptosai/mcp-observatory@latest protect rewrites every discovered client config (Cursor, Claude, VS Code, .mcp.json, …). Undo: protect --undo. HTTP/SSE servers are left alone.

Runtime deny-default: npx -y @kryptosai/mcp-observatory@latest enforce --start-proxy writes a Seatbelt policy from the scan and starts the proxy. Local scan stays free.

Proof: Safety Index. Local history, evidence export, CI, and remediation task preparation are free.

Learn from production usage

Connect real tool calls to user intent with the usage-learning SDK and CLI: sanitized invocation evidence, opted-in “asked / expected / got” reports, selected conversation excerpts, one-click dissatisfaction flags, intent grouping across captured requests, and regression-case export. Run mcp-observatory usage review --dir private-usage to inspect linked evidence in a loopback-only browser screen. Server logs cannot reveal unshared conversations; observed execution and inferred breakdown signals stay separate. Collection is local and requires explicit integration.

Why MCP Observatory

MCP servers are becoming production dependencies. If agents rely on them, teams need a way to catch broken tools, unsafe schemas, schema drift, slow responses, and security footguns before those failures reach users.

Observatory gives maintainers and teams:

• One-command CI setup with setup-ci --all
• Profile-mapped audits with audit --profile nsa-mcp
• MCP receipts that package target, evidence, verdict, action, and reproduction commands
• MCP risk graphs that group servers by capability boundary, receipt state, CI posture, and recommended action
• Action receipts that say allow, gate, rerun, quarantine, or escalate
• GitHub PR comments for compatibility, drift, and security findings
• GitHub Code Scanning SARIF for normalized MCP findings
• Health score badges for public trust signals
• Record/replay/verify workflows for regression testing
• MCP server mode so agents can inspect other MCP servers directly
• Review and remediation with free local history, CI, and optional ClearFrame CLI or Mac tasks

See GitHub Code Scanning for MCP servers, MCP Receipts, Troubleshooting, Safety Methodology, MCP Server Safety Index, MCP Observatory Contributors, hosted client contract, repository boundary, open-source policy, and free project policy.

Self-Assessment

We scan ourselves with mcp-observatory on every release. See results →

Self-hosted evidence

The MIT-licensed hosting source includes private receipt storage, GitHub sign-in, multi-target history, downloads, hosted HTTP checks and retention cleanup. Deploy it with your own configuration; no Observatory subscription is required. The account-free local dashboard is the fastest start.

Free tools for maintainers and teams

All scanner features, source audits, skill scans, package-name review, cross-server capability review, receipts, record/replay, local dashboards, and CI integrations are open source under MIT. No hosted account or private API is needed.

# Inspect local code without executing it

npx -y @kryptosai/mcp-observatory@latest source-audit ./src

Review a launch package name without running it

npx -y @kryptosai/mcp-observatory@latest package-check -- npx -y your-mcp-package

Review capability combinations across saved receipts

npx -y @kryptosai/mcp-observatory@latest toxic-flow first-receipt.json second-receipt.json

These checks identify review candidates; they do not prove a server is safe. See coverage and competitor feature evidence, ClearFrame workflow, and project policy.

How It Compares

Quick Start

Run a first check. No arguments starts demo (your servers, or the packaged local demo):

npx @kryptosai/mcp-observatory

Go deeper — also invoke safe tools to verify they actually run:

npx @kryptosai/mcp-observatory scan deep

Test a specific server:

npx @kryptosai/mcp-observatory test npx -y @modelcontextprotocol/server-everything

Add it to Claude Code as an MCP server:

claude mcp add mcp-observatory -- npx -y @kryptosai/mcp-observatory serve

Or add it manually to your config:

{

"mcpServers": { "mcp-observatory": { "command": "npx", "args": ["-y", "@kryptosai/mcp-observatory", "serve"] } } }

Commands

| scan | Auto-discover servers, check them, and run safe a