Spyglass

MCP Server Discovery & Governance Scanner

AI coding assistants routinely configure MCP servers with exposed credentials and unaudited remote connections, but there's been no standard way to discover or govern them. Spyglass closes that visibility gap — scanning configs across 8+ AI tools, flagging security risks, and feeding findings into enforcement policies.

In Active Development

Three-Tier MCP Governance

Spyglass is Tier 2 of a three-tier framework for MCP server governance. Discovery feeds enforcement, enforcement feeds fleet-wide visibility.

Tier 1

PrivMan Policy Pack

Execution-layer enforcement via Delinea Privilege Manager. Blocks tunnel service binaries, audits MCP runtimes, requires approval for remote connections.

Tier 2 — This Project

Spyglass Scanner

Application-layer discovery and audit. Scans MCP configs, flags credentials, detects tunnels and remote endpoints, reports findings as structured JSON.

Tier 3

Centralized Platform

Fleet-wide governance dashboard. Aggregate scan results across endpoints for organization-wide MCP posture visibility. (Roadmap)

What It Detects

Spyglass runs three analyzers against every discovered MCP server config: credential exposure, remote connections, and runtime inventory. Credential values are never stored in findings or output.

Credential Exposure

FindingSeverity
Env key name contains PASSWORD / SECRET / TOKEN / KEY / API_KEY / CREDENTIAL with plaintext string valueCRITICAL
Unknown plaintext env value (not a known non-secret, not a variable reference)HIGH
Inline credential flags in args: --password=, --token=, --secret=, --api-key=HIGH
Deferred environment variable reference (${ENV_VAR} or $ENV_VAR)LOW
VS Code input prompt variable (${input:ID})INFO

Remote Connections & Tunnels

FindingSeverity
Tunnel services: *.ngrok.io, *.ngrok-free.app, *.trycloudflare.com, *.loca.lt, *.bore.pubHIGH
Cloud endpoints: AWS (*.amazonaws.com), Azure (*.azurewebsites.net), GCP (*.run.app)MEDIUM
Any other HTTP/HTTPS URL in command argumentsMEDIUM
Non-localhost IP addresses in argumentsMEDIUM
Localhost patterns (127.0.0.1, 0.0.0.0, [::1])Safe — ignored

Runtime Inventory

Every server is profiled for runtime type, package, transport, source tool, and environment key names. Supports: node, npx, python, uvx, docker, deno, bun. Detects stdio vs SSE transport automatically from args and config fields.

Runtime type Package name Transport (stdio/SSE) Source file Source tool Environment keys Remote URL Command + args

Supported Tools

Scans global and project-level config files across all major AI coding assistants. Cross-platform: macOS, Windows, and Linux.

Claude Desktop
Claude Code
VS Code / Copilot
Cursor
Windsurf
Amazon Q
Goose
OpenAI Codex

Config Formats

Parses all formats used by AI tool MCP configurations, including non-standard variants.

JSON (strict) JSONC (comments + trailing commas) YAML TOML

Auto-detects root key structure (mcpServers, servers, or flat layout). Walks project directories up to 3 levels deep, skipping .git, .venv, node_modules, and other VCS/build dirs.

Webhook Notifications

Send scan summaries to your team's collaboration platform after every scan. Includes hostname, OS, server count, findings by severity, and top 5 critical/high findings.

Slack

Block Kit formatted messages

Microsoft Teams

Adaptive Card via Incoming Webhook

Webex

Markdown formatted summary

# Scan and notify Slack
spyglass scan --notify slack --webhook-url $SLACK_WEBHOOK

# Scan and notify Teams
spyglass scan --notify teams --webhook-url $TEAMS_WEBHOOK

CI/CD Integration

Use severity thresholds to fail builds when risky MCP configs are detected. Exit code 1 when findings meet or exceed the threshold.

# Fail if any HIGH or CRITICAL findings
spyglass scan --threshold HIGH

# Fail on MEDIUM and above
spyglass scan --threshold MEDIUM --output report.json

# Full pipeline: scan projects, report, notify, gate
spyglass scan \
--project-roots ~/Projects,~/work \
--output report.json \
--notify slack --webhook-url $WEBHOOK \
--threshold HIGH

MCP Server Mode

Spyglass can run as an MCP server itself, exposing a scan_configs tool that AI assistants can call directly. Query your MCP posture from inside Claude, Claude Code, or any MCP-compatible client.

# Run as MCP server (stdio transport)
spyglass serve

# With project scanning
spyglass serve --project-roots ~/Projects

Exposed tool: scan_configs — accepts optional project_roots, extra_paths, and exclude_paths parameters. Returns the full scan result as structured JSON with servers, findings, and summary.

Tech Stack

Python 3.10+ Click CLI PyYAML MCP SDK (FastMCP) Hatchling pytest Docker pathlib (cross-platform)

Quick Start

# Install
pip install -e .

# Basic scan (JSON to stdout)
spyglass scan

# Scan specific project directories
spyglass scan --project-roots ~/Projects,~/work

# Write report to file
spyglass scan --output report.json

# Skip global configs, scan only specified paths
spyglass scan --no-global --extra-paths /opt/custom/mcp-config.json

# Load options from YAML config
spyglass scan --config scan-config.yaml

# Run as MCP server for AI assistant integration
spyglass serve

Project Structure

spyglass/ pyproject.toml # Package config, dependencies, entry points Dockerfile src/spyglass/ cli.py # Click CLI: scan + serve commands scanner.py # Core: discover configs, parse, analyze analyzers.py # Credential, remote connection, runtime analysis parsers.py # JSON, JSONC, YAML, TOML parsing models.py # Finding, ServerInfo, ScanResult dataclasses paths.py # Platform-aware config path resolution notify.py # Slack, Teams, Webex webhook notifications mcp_server.py # MCP server mode (scan_configs tool) tests/ test_scanner.py # End-to-end scan tests test_parsers.py # Format parsing tests test_analyzers.py # Security analyzer tests test_cli.py # CLI integration tests docs/ tier1-policy-pack.md # Tier 1 PrivMan enforcement policies tier1-filter-guide.md # PrivMan filter configuration guide