Skip to main content
Glama
infra-lens-mcp
by oaslananka

infra-lens-mcp connects to Linux hosts over SSH, captures bounded live metrics, stores observations and approved baselines in local SQLite, explains anomalies, and produces review-first incident artifacts. The npm package and signed container are release-ready; public connector publication remains intentionally blocked until an external OAuth/HTTPS deployment is verified.

Demo

infra-lens-mcp demo

See the MCP 2025-11-25 compliance matrix for current protocol support, delegated behavior, and connector publication constraints.

Related MCP server: Linux MCP Server

Tools

Tool

Purpose

analyze_server

Analyze a bounded sampled window with progress/cancellation support, then store only the completed observation

analyze_server_snapshot

Analyze and store one immediate snapshot without a sampling delay

snapshot

Store a point-in-time observation without anomaly analysis

record_baseline

Save a labeled healthy-state sample

compare_to_baseline

Compare current state with a named baseline

get_history

Return CPU, memory, or load history from SQLite

inspect_host_capabilities

Check required Linux commands and proc files before collection

plan_remediation

Propose evidence-backed, approval-required remediation without executing changes

draft_incident_report

Draft an incident report and postmortem from persisted observations

compare_incident_windows

Compare adjacent windows for one host or the same window across two hosts

All tools return both readable JSON text and MCP structuredContent validated by declared outputSchema definitions, so clients and agents can consume responses without parsing the text block. Collection tools include a warnings array when optional sections cannot be collected but a partial snapshot is still usable. Use analyze_server_snapshot for interactive checks; use analyze_server only when a sampled window is required. Sampled analysis emits MCP progress when the client supplies a progress token and never persists a cancelled partial run.

Requirements

  • Node.js 24 LTS for CI, Docker, and release workflows

  • Node.js 22 or newer for package runtime compatibility

  • pnpm 11.15.1 through Corepack for development installs

  • Linux SSH targets with /proc, free, df, ps, and uname

  • Strict SSH host verification through known_hosts or pinned SHA256 host keys

Quick Start

Run the stdio MCP server from npm:

npx -y infra-lens-mcp

Desktop MCP client style configuration:

{
  "mcpServers": {
    "infra-lens": {
      "command": "npx",
      "args": ["-y", "infra-lens-mcp"],
      "env": {
        "INFRA_LENS_DB": "/Users/you/.infra-lens-mcp/metrics.db"
      }
    }
  }
}

Local development:

corepack enable
corepack prepare pnpm@11.15.1 --activate
pnpm install --frozen-lockfile
pnpm run build
node dist/mcp.js

Configuration

Transport is selected by the executable entry point, not by an environment variable: npx -y infra-lens-mcp or node dist/mcp.js starts stdio, while node dist/server-http.js starts Streamable HTTP.

Variable

Default

Description

INFRA_LENS_DB

~/.infra-lens-mcp/metrics.db

SQLite database path

INFRA_LENS_RETENTION_DAYS

30

Snapshot retention in days; 0 disables automatic pruning

MCP_HTTP_HOST

127.0.0.1

HTTP bind host. HOST remains a deprecated alias

MCP_HTTP_PORT

3000

HTTP bind port. PORT remains a deprecated alias

MCP_HTTP_ENDPOINT_PATH

/mcp

Canonical Streamable HTTP MCP endpoint path

MCP_HTTP_ALLOWED_ORIGINS

unset

Comma-separated allowed Origin values

MCP_HTTP_ALLOWED_HOSTS

unset

Comma-separated allowed Host values

MCP_HTTP_AUTH_MODE

none

none, bearer, or oauth-gateway; oauth is accepted as a compatibility alias

MCP_HTTP_BEARER_TOKEN

unset

Local/dev bearer fallback token

MCP_HTTP_OAUTH_GATEWAY_HEADER

x-infra-lens-gateway-auth

Header injected by a trusted OAuth gateway

MCP_HTTP_OAUTH_GATEWAY_SECRET

unset

Shared backend secret required for oauth-gateway mode

MCP_HTTP_BODY_LIMIT_BYTES

1048576

Maximum JSON request body size

MCP_HTTP_REQUEST_TIMEOUT_MS

30000

Maximum time to receive and handle an HTTP request before the socket is closed

MCP_HTTP_MAX_CONCURRENT_REQUESTS

100

Maximum concurrent HTTP requests accepted by the Node process

MCP_HTTP_RATE_LIMIT_PER_MINUTE

0

Optional per-client in-memory rate limit; 0 disables it

MCP_HTTP_AUTHORIZATION_SERVERS

unset

OAuth authorization server metadata URLs

MCP_PROFILE

full

full, remote-safe, chatgpt, or claude

MCP_SSH_STRICT_HOST_CHECKING

true

Strict host key verification toggle

MCP_SSH_KNOWN_HOSTS

~/.ssh/known_hosts

Known hosts file

MCP_SSH_ALLOWED_HOSTS

unset

Exact host/IP or IPv4 CIDR allowlist; required for remote-safe profiles and enforced in full profile when set

MCP_SSH_ALLOWED_USERS

unset

Optional comma-separated SSH username allowlist

MCP_SSH_ALLOWED_PORTS

unset

Optional comma-separated SSH port allowlist

MCP_SSH_MAX_SESSIONS_PER_HOST

0

Optional active SSH session cap per host:port; 0 disables it

MCP_SSH_MAX_CONNECTION_ATTEMPTS_PER_MINUTE

0

Optional SSH connection-attempt cap per host:port per minute; 0 disables it

MCP_DB_PATH from older examples is not used; use INFRA_LENS_DB.

SSH Security

Strict host key checking is enabled by default. Provide either:

  • a hostKeySha256 value in the connection input, such as SHA256:...

  • a knownHostsPath in the connection input

  • MCP_SSH_KNOWN_HOSTS pointing at an OpenSSH known_hosts file

Raw passwords, private keys, and passphrases are accepted only in the default full profile for trusted local MCP contexts. remote-safe, chatgpt, and claude profiles reject raw SSH credentials in tool input and require MCP_SSH_ALLOWED_HOSTS. Production SSH policy can also restrict exact hosts or IPv4 CIDR ranges, users, ports, per-host active sessions, and per-host connection attempts.

Process command arguments are not collected by the default process command. Secret-like values in process data, SSH errors, and logs are redacted before storage or output.

HTTP Transport

Run the Streamable HTTP transport locally. The canonical MCP endpoint is http://127.0.0.1:3000/mcp unless MCP_HTTP_ENDPOINT_PATH is changed. HTTP mode is stateless today: the server does not issue or accept MCP-Session-Id, and only POST JSON-RPC calls are supported on the MCP endpoint. MCP_HTTP_REQUEST_TIMEOUT_MS and any proxy timeout must exceed the requested sampled window; otherwise use analyze_server_snapshot. stdio has no server-owned wall-clock request timeout, so the client controls its timeout and MCP cancellation.

MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=3000 node dist/server-http.js

Loopback HTTP can run without auth for local development. Any non-loopback bind, such as 0.0.0.0, fails fast unless all of these are configured:

  • MCP_PROFILE=remote-safe, chatgpt, or claude

  • MCP_HTTP_AUTH_MODE=bearer or oauth-gateway

  • MCP_HTTP_ALLOWED_ORIGINS

  • MCP_HTTP_ALLOWED_HOSTS

Native OAuth/JWT validation is not implemented inside this package. Public deployments should use MCP_HTTP_AUTH_MODE=oauth-gateway behind a production OAuth-aware gateway or reverse proxy, configure HTTPS MCP_HTTP_RESOURCE_URL, and block direct access to the Node process. Keep origin/host allowlists, body limits, request timeout, concurrency limit, and optional rate limit enabled at the Node process even when an upstream proxy also enforces them. See ADR 0006. Connector publication readiness remains false until a full connector deployment is verified.

Docker

The Docker image defaults to stdio mode:

docker build -t infra-lens-mcp .
docker volume create infra-lens-data
docker run --rm -i \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges:true \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  --mount type=volume,src=infra-lens-data,dst=/home/appuser/.infra-lens-mcp \
  infra-lens-mcp

For local HTTP testing, override the command and keep the bind host on loopback unless a remote-safe profile and auth controls are configured:

docker run --rm -p 127.0.0.1:3000:3000 \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges:true \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  --mount type=volume,src=infra-lens-data,dst=/home/appuser/.infra-lens-mcp \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_ALLOWED_ORIGINS=http://localhost:3000 \
  -e MCP_HTTP_ALLOWED_HOSTS=localhost:3000 \
  -e MCP_HTTP_AUTH_MODE=bearer \
  -e MCP_HTTP_BEARER_TOKEN=local-dev-token \
  infra-lens-mcp node dist/server-http.js

Observability exports

Observability is a separate, disabled-by-default process that reads the latest persisted observations without initiating SSH collection:

INFRA_LENS_OBSERVABILITY_ENABLED=true infra-lens-observe

The default OpenMetrics endpoint is http://127.0.0.1:9464/metrics. Optional OTLP/HTTP JSON export uses standard OTEL_EXPORTER_OTLP_* variables. See Observability exports for Prometheus, OpenTelemetry, privacy, and remote-access guidance.

Development

pnpm run format:check
pnpm run lint
pnpm test
pnpm run test:coverage
pnpm run build
pnpm run check:metadata
pnpm run package:dry-run

Docker-backed SSH e2e validation uses a self-contained fixture lifecycle:

pnpm run test:e2e

If a fixture is already running and you intentionally want to skip lifecycle management, use:

INFRA_LENS_E2E_SKIP_FIXTURE=1 pnpm run test:e2e:raw

Start with the documentation index for usage, client setup, operations, incident workflows, observability, storage, security, governance, testing, and release guidance. Generated API docs live in docs/api, and reviewed incident examples live in examples/incidents.

Community

Use SUPPORT.md for support channels and response expectations. Active work is tracked in the infra-lens-mcp Governance project. Project conduct is defined in CODE_OF_CONDUCT.md, and maintainer triage policy lives in docs/governance.md.

Release

Releases are managed through release-please manifest mode and the guarded GitHub Actions release workflow. Implementation PRs must not publish packages, containers, MCP Registry entries, marketplace artifacts, or production GitHub Releases.

See docs/release.md and docs/release-state-machine.md.

License

MIT

Agent plugin and runtime configuration

This repository owns the product-level agent plugin, MCP runtime configuration, and product-specific skills for infra-lens-mcp. The central agent-tools repository should catalog this plugin, but the manifest and workflow instructions live here so they stay synchronized with the actual MCP server package.

File

Purpose

.claude-plugin/plugin.json

Claude Code-valid product plugin manifest.

.mcp.json

Claude Code project-local MCP server configuration.

.codex/config.example.toml

Codex CLI MCP configuration example.

.vscode/mcp.example.json

VS Code / GitHub Copilot workspace MCP configuration example.

opencode.example.jsonc

OpenCode project MCP configuration example.

.opencode/skills/

OpenCode-native mirrored skill definitions.

docs/agent-runtime-config.md

Agent runtime setup and validation notes.

Validate plugin packaging locally:

claude plugin validate .

For review-first remediation plans, incident drafts, and host/time-window comparisons, see Incident workflows.

Available Tools

10 tools
analyze_serverAnalyze ServerB

Collect metrics from a server and explain any anomalies in human language

Inputs: connection (required), include_network, duration_minutes, include_processes. Returns: host, metrics, summary, warnings, +6 more

analyze_server_snapshotAnalyze Current Server SnapshotC

Collect one immediate server snapshot, analyze it, and persist the completed observation without a sampling delay

Inputs: connection (required), include_network, include_processes. Returns: host, metrics, summary, warnings, +6 more

compare_incident_windowsCompare Incident WindowsA
Read-only

Compare adjacent time windows for one host or the same recent window across two hosts

Inputs: host (required), limit, compare_host, recent_hours, +1 more. Returns: left, right, metrics, summary, +5 more

compare_to_baselineCompare to BaselineB
Read-only

Compare current server state to a recorded baseline and explain the differences

Inputs: connection (required), baseline_label. Returns: host, summary, warnings, anomalies, +3 more

draft_incident_reportDraft Incident ReportB
Read-only

Create a review-first incident report and postmortem draft from persisted observations

Inputs: host (required), hours, limit. Returns: host, status, window, timeline, +10 more

get_historyGet Metric HistoryB
Read-only

Get historical CPU, memory, or load values for a server

Inputs: host (required), hours, label, limit, +2 more. Returns: host, hours, label, metric, +4 more

inspect_host_capabilitiesInspect Host CapabilitiesB
Read-only

Check whether a Linux host supports infra-lens collection

Inputs: connection (required). Returns: host, warnings, checked_at, capabilities

plan_remediationPlan RemediationA
Read-only

Collect a current read-only snapshot and produce approval-required remediation guidance without executing changes

Inputs: connection (required). Returns: host, steps, summary, confidence, +4 more

record_baselineRecord BaselineA

Record current metrics as baseline during normal operation for more accurate anomaly detection later

Inputs: connection (required), label. Returns: host, label, saved, message, +2 more

snapshotTake Metric SnapshotB

Collect and save current server metrics without analysis

Inputs: connection (required). Returns: host, saved, warnings, timestamp

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 10 tools

    Disambiguation3/5

    Several tools have overlapping purposes, especially analyze_server and analyze_server_snapshot which both collect and analyze metrics with subtle differences in timing and persistence. snapshot and analyze_server_snapshot also share collection behavior, while compare_to_baseline and compare_incident_windows both perform comparisons in different contexts. Descriptions provide some clarity, but boundaries are not always obvious.

    Naming Consistency4/5

    Most tool names follow a verb_noun pattern (analyze_server, record_baseline, compare_to_baseline, get_history, inspect_host_capabilities, plan_remediation, draft_incident_report, compare_incident_windows). However, 'snapshot' is a bare noun, and 'analyze_server_snapshot' diverges from the simpler 'analyze_server' pattern, introducing minor inconsistency.

    Tool Count5/5

    With 10 tools, the server covers monitoring, baselining, comparison, history, remediation, and incident reporting without feeling bloated. Each tool addresses a distinct aspect of the infrastructure analysis workflow, and the count is well within the ideal range.

    Completeness4/5

    The tool set covers the core lifecycle of server monitoring: collection, analysis, baseline recording/comparison, historical lookup, host capability checks, remediation planning, and incident reporting. Minor gaps exist, such as no explicit tools to list or delete saved baselines or snapshots, but these do not cripple the main workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables read-only Linux system diagnostics and troubleshooting on local and remote RHEL-based systems via SSH, including services, processes, logs, network, and storage analysis.
      20
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      An MCP server for read-only Linux system administration and diagnostics on RHEL-based systems via SSH. It enables users to troubleshoot remote hosts by accessing system information, services, logs, and network configurations through natural language.
      23
      726 PyPI
      323
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that provides guarded, audited, read-only access to ops tooling (alerts, metrics, logs, deploys, runbooks) and a triage agent that diagnoses incidents end-to-end with CI-verified root cause analysis.
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables stdio MCP clients to gather read-only diagnostics and incident evidence from Linux homelabs, including health, disks, services, Docker containers, logs, and confirmation-required remediation proposals.
      10
      MIT