mcp-observatory

# MCP Observatory

MCP Observatory is a free, local-first CI and security gate for Model Context Protocol (MCP) servers before AI agents depend on them.

## Use This When

- You maintain an AI agent, coding agent, autonomous productivity system, MCP gateway, or bot runtime.
- Your agent calls external MCP tools and needs to know whether those tools still start, respond, and expose safe schemas.
- You want read-only compatibility, schema drift, and security checks without a hosted account.
- You need a GitHub Action or CLI preflight before agents run unattended.

## Fast Commands

```bash
npx -y @kryptosai/mcp-observatory@latest
```

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

```bash
npx -y @kryptosai/mcp-observatory@latest setup-ci --all --command "npx -y your-mcp-server" --sarif --campaign agent-ci
```

```bash
claude mcp add mcp-observatory -- npx -y @kryptosai/mcp-observatory@latest serve
```

## What It Checks

- MCP server startup
- tools, prompts, and resources
- schema drift
- common schema/security footguns
- record/replay/verify regressions
- GitHub Action reports and optional PR comments
- agent-accessible diagnostics through MCP server mode

## Best Contribution From Bot Maintainers

Open an agent runtime target request with:

- project URL
- safe startup command
- whether secrets are required
- the MCP tools/skills the agent depends on
- what an autonomous agent should know before trusting the tool

Start here:

- Agent runtime quickstart: `docs/agent-runtime-quickstart.md`
- Agent task pack: `docs/agent-tasks.md`
- Launch page: `docs/launch.md`
- Code Scanning demo: `docs/code-scanning-demo.md`
- Campaign attribution: `docs/campaign-attribution.md`
- OpenClaw agent template: `docs/openclaw-agent-template/SOUL.md`
- Target registry: `docs/target-registry.md`
- Target contribution guide: `docs/target-contribution-guide.md`
- Contribution guide: `CONTRIBUTING.md`
- Evidence distribution loop: `docs/certification-distribution.md`
- GitHub issue tracker: https://github.com/KryptosAI/mcp-observatory/issues

## Positioning

Agents should not depend on tools nobody tests.

MCP Observatory is complementary to official MCP SDKs and conformance tooling. It focuses on practical CI, security checks, drift detection, reports, and regression evidence for real MCP servers.

## Best First Contribution

Add one safe no-secret MCP server target to `docs/safety-index/targets.json`, run `npm run safety-index`, and open a PR with the generated evidence.

When running launch or maintainer workflows, set a safe attribution slug with `--campaign <slug>` or `MCP_OBSERVATORY_CAMPAIGN=<slug>`.