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

There are several ways to send telemetry to Spanly. They all produce the same data; pick whichever fits your stack.

TypeScript

npm install @spanly/sdk

import { SpanlyClient } from "@spanly/sdk";const spanlyClient = new SpanlyClient({  apiKey: process.env.SPANLY_API_KEY,});// const mcpServer = new McpServer({ name: "your-mcp-server-name", version: "1.0.0" });// Monitor your MCP server (one line!)spanlyClient.monitor(mcpServer);// mcpServer.connect(transport);

Python

pip install spanly
# or: uv add spanly

from spanly import SpanlyClientspanly_client = SpanlyClient(    api_key=os.environ["SPANLY_API_KEY"],)# server = MCPServer("your-mcp-server-name", version="1.0.0")# Monitor your MCP server (one line!)spanly_client.monitor(server)# server.run()

Any language: wrap the binary with the CLI

If your server is in Go, Rust, or any other language, run it under the Spanly CLI instead. No code changes required.

# 1. Set your API key (region auto-detected from the prefix)export SPANLY_API_KEY="$SPANLY_API_KEY"# 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

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.
• Latency (request received to response sent).
• HTTP context (path, status, transport: stdio / HTTP / SSE).
• Server and client name + version from the MCP initialize handshake.
• Errors, including stack traces when available.

Nothing else leaves your process. No request body or response body is modified. The SDK and CLI both forward the original bytes verbatim.

What's next

• The TypeScript SDK reference covers the full SpanlyClient API, including per-request hooks for filtering and multi-tenant tagging.
• 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.