Quickstart

Spanly is the observability platform for Model Context Protocol servers and AI agents. Drop in an SDK or run the CLI in front of your server, and every JSON-RPC packet (tools, prompts, resources, errors) streams to a dashboard you can search, slice, and alert on.

1. Create a project and grab an API key

1. Sign up at spanly.com.
2. Create a project (or use the default one).
3. Go to Settings → API keys and copy the key. It starts with spanly_us_ or spanly_eu_. The region is encoded in the prefix, so you do not have to configure it separately.

Set it in your shell:

export SPANLY_API_KEY=spanly_us_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Always read the key from the environment. Never hard-code it.

2. Pick an integration path

All paths produce the same data; pick whichever fits your stack.

Fastest path: wrap your server with the CLI

No code changes, works for any language, stdio or HTTP:

# 1. Set your API key (region auto-detected from the prefix)export SPANLY_API_KEY=spanly_us_xxxxxxxxxxxx# 2. Wrap your MCP server. stdio:npx -y @spanly/spanly run -- node ./server.js# Or HTTP. The wrapper takes your port; the child gets a random one:npx -y @spanly/spanly run --port 3000 -- node ./server.js

That's the whole integration. Skip to step 3.

Prefer in-process middleware?

The SDKs are HTTP (TypeScript) and ASGI (Python) middleware: mount them in front of your existing MCP server and identify end users from your own auth state with the identity option.

TypeScript

npm install @spanly/sdk

import express from "express";import { spanly } from "@spanly/sdk";const app = express();app.use(spanly({ apiKey: process.env.SPANLY_API_KEY }));// app.use("/mcp", mcpRouter);

Python

pip install spanly
# or: uv add spanly

import osfrom spanly import SpanlyMiddlewareapp.add_middleware(SpanlyMiddleware, api_key=os.environ["SPANLY_API_KEY"])

3. Run your server normally

The SDK and the CLI both run the server unchanged. No new ports, no extra processes from the user's perspective. Talk to it from your MCP client (Claude Desktop, Cursor, Windsurf, a Python script) as you would normally.

4. See the request in the dashboard

Open spanly.com, pick your project, and head to the Requests view. Within a few seconds of the first MCP call, you will see a row appear with the method, server, client, duration, and a link to the full JSON-RPC payload.

What gets captured

For every MCP request, Spanly records:

• The raw JSON-RPC request and response.
• Tool / prompt / resource name and arguments.
• Duration (request received to response sent).
• Transport metadata. For HTTP: method, path, and headers.
• Server and client name + version from the MCP initialize handshake.
• Errors, including stack traces when available.

Credential-bearing headers (Authorization, Cookie, Set-Cookie, Proxy-Authorization, X-Api-Key, X-Auth-Token, X-Amz-Security-Token, X-Forwarded-Authorization) are replaced with [REDACTED] before the telemetry packet leaves your process, so secrets never reach Spanly. You can extend the list with the redactHeaders SDK option or the CLI's --redact-header flag.

Nothing else leaves your process. No request body or response body is modified. The SDK and CLI both forward the original bytes verbatim, including the original headers; only the telemetry copy is redacted.

Data handling

• Redaction: credential-bearing headers are redacted automatically (see above); attribute traffic to an end user instead of dropping it with the SDK's identity option (TypeScript) or the Python equivalent. With the CLI, --inspect-prefix limits capture to specific paths; the SDKs' paths option does the same.
• Retention: captured requests are kept for 30 days on Free, 90 days on Pro, and 365 days on Business. See pricing.
• Residency: data is stored in the region your API key belongs to (US or EU) and never leaves it. See the security overview and privacy policy.

What's next

• The TypeScript SDK reference covers the full spanly() and wrapFetchHandler() middleware, including the identity option for end-user attribution.
• The Python SDK reference is the equivalent for Python.
• The CLI reference lists every flag for spanly run and spanly proxy.
• If nothing shows up in the dashboard, check the troubleshooting guide first.