Spanlens

io.github.spanlensPublished by GitHub account spanlensv0.3.0Updated Oct 27, 2026

Query Spanlens LLM observability from Cursor, Claude Desktop, or Continue via MCP.

VerifiedSTDIODesktop onlySecurity & MonitoringData & AnalyticsAI & ML

Overview

AI-generated overview

Spanlens MCP server lets an assistant query your Spanlens LLM observability workspace for spend, requests, traces, anomalies and savings.

What you can do
  • Get aggregate cost, request count, token usage, latency and error rate, optionally grouped by model or provider
  • List and filter individual LLM requests by model, provider, status, user, time window and limit
  • List agent trace summaries and pull the full span tree for a single trace
  • Retrieve detected cost, latency and error-rate anomalies with an adjustable window and sensitivity
  • Get model-swap savings recommendations and per-end-user usage breakdowns
When to use it
Useful when you already send LLM usage data to Spanlens and want to ask about spend, latency, errors, traces or cost anomalies from inside Cursor, Claude Desktop or Continue instead of opening the dashboard.
Requirements
Runs locally over stdio via npx from the npm package, so Node.js is needed. Requires a Spanlens public-scope API key in SPANLENS_API_KEY; the server refuses to start without one or with a full-access key. Network access to the Spanlens API is required; SPANLENS_BASE_URL can point at a self-hosted instance, and SPANLENS_TIMEOUT_MS sets the per-call timeout.
Before you install
The API key sits in a plaintext IDE config file that can leak through dotfile sync, screen sharing or accidental commits; only a read-only public-scope key is accepted, and a leaked one cannot trigger proxy spend. The server reads usage and trace data, including per-end-user usage, from your workspace and sends it to the configured API endpoint.

Installation

In SourceWeft

  1. Open Spanlens in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@spanlens/mcp-server

Query your LLM observability data from inside Cursor, Continue, or Claude Desktop. Powered by Spanlens.

Ask your IDE's agent things like "what's my OpenAI spend this week?", "any cost anomalies?", or "show me the most expensive trace today" — and get real answers from your Spanlens workspace through the Model Context Protocol.

30-second setup

1. Issue a public-scope Spanlens key

Public-scope keys (sl_live_pub_*) are read-only — they can query your dashboard data but cannot trigger LLM proxy spend. This server refuses to start with a full-access key because the credential will live in a plaintext config file in your IDE.

Create one at spanlens.io/projects → the Public Keys card at the top → + New public key. Copy the sl_live_pub_… value when it's shown.

2. Add the server to your IDE

Cursor — ~/.cursor/mcp.json (or workspace .cursor/mcp.json)
json
{  "mcpServers": {    "spanlens": {      "command": "npx",      "args": ["-y", "@spanlens/mcp-server"],      "env": { "SPANLENS_API_KEY": "sl_live_pub_..." }    }  }}
Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
json
{  "mcpServers": {    "spanlens": {      "command": "npx",      "args": ["-y", "@spanlens/mcp-server"],      "env": { "SPANLENS_API_KEY": "sl_live_pub_..." }    }  }}
Continue — ~/.continue/config.yaml
yaml
mcpServers:  - name: spanlens    command: npx    args: ['-y', '@spanlens/mcp-server']    env:      SPANLENS_API_KEY: sl_live_pub_...

3. Reload your IDE and start asking

The agent will discover seven tools and use them automatically when relevant.

What you can ask

QuestionTool called
"How much have we spent on LLMs this week?"get_stats
"Break down cost by model for the last 30 days"get_stats(groupBy=model)
"Which provider is costing us the most this week?"get_stats(groupBy=provider)
"Any cost or latency anomalies?"get_anomalies
"Show me the 10 most recent error calls on gpt-4o"query_requests
"List my recent agent runs"list_traces
"Walk me through trace abc123…"get_trace
"What models could we swap to save money?"get_savings
"Which end-user is driving the most spend?"get_user_analytics

Available tools

ToolWhat it returns
get_statsAggregate cost, request count, token usage, latency, error rate. Optional groupBy for a breakdown of cost, requests, latency and error rate: model returns one row per provider and model pair, and provider rolls those rows up into one row per provider, with latency and error rate weighted by request count.
query_requestsIndividual LLM requests with cost, latency, model, error message. Filter by model, provider, status, userId, since, limit.
list_tracesAgent trace summaries (name, status, duration, span count, total tokens, total cost) for discovering trace IDs. Filter by limit, status, since, query. Pair with get_trace for the full span tree.
get_traceFull agent span tree for a trace ID — every LLM/tool/retrieval span with timing, tokens, cost.
get_anomaliesCost / latency / error-rate anomalies the platform has detected. Optional since (observation window) and sigma (sensitivity).
get_savingsModel-swap recommendations with projected monthly savings and adoption status.
get_user_analyticsPer-end-user usage breakdown — total cost, request count, models touched, recent calls.

Safety

This server is designed for the IDE-config use case, where the credential sits in a plaintext file that's easy to leak (dotfile sync, screen shares, accidental commits). Two defenses:

  1. Public-scope keys only. The server boots, calls /api/v1/me/key-info against your workspace, and verifies the key has scope=public. If you accidentally paste a full-access sl_live_* key, the server refuses to start with a clear error pointing at the correct key type.
  2. Read-only at the API layer. Even if a public key leaks, it cannot call /proxy/* or /ingest/* — the Spanlens server enforces this with a 403 + PUBLIC_KEY_WRITE_FORBIDDEN code. The blast radius of a leak is "competitor sees my usage stats", not "competitor runs up my OpenAI bill".

Configuration

Environment variableDefaultNotes
SPANLENS_API_KEYrequiredA sl_live_pub_* key from the Public Keys card on /projects. The server refuses to start without one, and refuses to start with a sl_live_* (full) key.
SPANLENS_BASE_URLhttps://api.spanlens.ioOverride for self-hosted Spanlens. Trailing slashes are normalised.
SPANLENS_TIMEOUT_MS30000How long each API call may take, in milliseconds, before it fails with a timeout error. Applies to the startup key check and to every tool call. Accepts a whole number from 1 to 600000. Any other value stops the server at startup with an error that names the variable.

Self-hosted Spanlens

json
{  "mcpServers": {    "spanlens": {      "command": "npx",      "args": ["-y", "@spanlens/mcp-server"],      "env": {        "SPANLENS_API_KEY": "sl_live_pub_...",        "SPANLENS_BASE_URL": "https://spanlens.your-company.com"      }    }  }}

Links

License

MIT — see LICENSE in the repo root.

Source: packages/mcp-server/README.md at commit e825a7e

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v0.3.0LatestSep 28, 2026
  2. v0.2.1Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts