About spanlens
spanlens is an MCP server for querying Spanlens LLM observability data from IDE agents and clients. Its tools cover usage and costs, request details, traces, anomalies, savings recommendations, and per-user analytics; it accepts read-only public-scope keys only.
Key features
- 01Aggregate usage and cost statistics
- 02Filterable request records
- 03Agent trace and span details
- 04Cost and latency anomaly queries
- 05Model-swap savings recommendations
- 06Per-user usage analytics
Use cases
- 01Reviewing weekly LLM spend by provider
- 02Investigating errors and expensive traces
- 03Finding cost or latency anomalies
MCP support
Exposes seven read-only Spanlens analytics tools to MCP clients such as Cursor, Continue, and Claude Desktop. It verifies that the configured API key has public scope and rejects full-access keys.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y @spanlens/mcp-serverSPANLENS_API_KEYSecretSpanlens API key. Must be a scope=public key (sl_live_pub_*) issued from the Public Keys card at https://spanlens.io/projects — the server refuses to start with a full-access sl_live_* key.SPANLENS_BASE_URLOverride the API endpoint for self-hosted Spanlens. Default: https://api.spanlens.ioLocal servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project 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)
{
"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)
{
"mcpServers": {
"spanlens": {
"command": "npx",
"args": ["-y", "@spanlens/mcp-server"],
"env": { "SPANLENS_API_KEY": "sl_live_pub_..." }
}
}
}
Continue — ~/.continue/config.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
| Question | Tool 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
| Tool | What it returns |
|---|---|
get_stats | Aggregate 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_requests | Individual LLM requests with cost, latency, model, error message. Filter by model, provider, status, userId, since, limit. |
list_traces | Agent 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_trace | Full agent span tree for a trace ID — every LLM/tool/retrieval span with timing, tokens, cost. |
get_anomalies | Cost / latency / error-rate anomalies the platform has detected. Optional since (observation window) and sigma (sensitivity). |
get_savings | Model-swap recommendations with projected monthly savings and adoption status. |
get_user_analytics | Per-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:
- Public-scope keys only. The server boots, calls
/api/v1/me/key-infoagainst your workspace, and verifies the key hasscope=public. If you accidentally paste a full-accesssl_live_*key, the server refuses to start with a clear error pointing at the correct key type. - 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_FORBIDDENcode. The blast radius of a leak is "competitor sees my usage stats", not "competitor runs up my OpenAI bill".
Configuration
| Environment variable | Default | Notes |
|---|---|---|
SPANLENS_API_KEY | required | A 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_URL | https://api.spanlens.io | Override for self-hosted Spanlens. Trailing slashes are normalised. |
SPANLENS_TIMEOUT_MS | 30000 | How 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
{
"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.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.