Installation

The Spanly CLI is a small Go binary distributed under the npm name @spanly/spanly. It captures MCP traffic from any server in any language, with no code changes.

npm (recommended for MCP client configs)

npx -y @spanly/spanly run -- node ./server.js

npx fetches the right binary for your OS on first run and caches it. This is the recommended path for embedding the CLI directly in Claude Desktop, Cursor, Windsurf, and other MCP client configs – no install step required.

Homebrew (macOS, Linux)

brew install spanly/tap/spanly
spanly run -- node ./server.js

Direct download

Grab the latest binary for your platform from the GitHub Releases page. Drop it on your PATH:

sudo install spanly /usr/local/bin/
spanly version

From source

go install github.com/spanlyhq/spanly/cli@latest

Docker

docker pull spanly/spanly:latest

See the Docker section for sidecar and compose patterns.

Configure the API key

The CLI reads SPANLY_API_KEY from the environment. The region is encoded in the prefix (spanly_us_… / spanly_eu_…) and auto-detected:

export SPANLY_API_KEY=spanly_us_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

For self-hosted or local development deployments, override the ingest endpoint with SPANLY_INGEST_URL.

Verify

spanly version
# spanly v1.4.2 (commit abc1234, built 2026-05-25)

Platforms

Two modes

The CLI has two subcommands:

• spanly run – wraps your MCP server as a child process. Works for stdio and HTTP transports. This is the default path for most users.
• spanly proxy – a standalone HTTP/SSE reverse proxy. Use when you can't wrap the child (third-party services, declarative k8s sidecars, network-level interception).

Both subcommands share the same flag surface for buffering, retry, admin endpoints, and OTLP co-export. See the flag reference.