Query LLM observability data, cost metrics, and agent traces directly from your IDE using Spanlens workspace data.
Also known as spanlens/Spanlens, @spanlens/mcp-server
- Stars
- 13
- Tools
- 7
- Downloads, 30 days
- —
- Latest version
- 0.3.0
- Last commit
- Nov 16, 2026
- License
- MIT
What is Spanlens MCP?
Spanlens queries LLM observability data, cost metrics, and agent traces directly from your IDE using Spanlens workspace data. It exposes 7 tools, such as get_stats, query_requests, list_traces.
Summary generated from the project's README
About Spanlens MCP server
Querying LLM observability data and cost metrics from inside your coding environment is what this server enables for developers using Cursor, Continue, or Claude Desktop. By connecting your Spanlens workspace via the Model Context Protocol, you can ask your IDE agent about OpenAI spending, cost anomalies, or specific agent traces without leaving your editor.
Setup requires a read-only public-scope Spanlens key, which ensures that even if your configuration file is exposed, your LLM proxy spend remains protected. The server runs locally through npx and uses the SPANLENS_API_KEY environment variable to authenticate. It is designed specifically for safety, refusing to start if a full-access key is provided.
Users can access seven specialized tools to retrieve data. These include get_stats for aggregate cost and latency, query_requests for individual LLM call details, and list_traces to find agent execution summaries. For deeper analysis, get_trace provides full span trees, while get_savings offers model-swap recommendations to reduce expenses.
What you can do with it
- 1Monitor LLM expendituresAsk your IDE agent to calculate your total spending on language models for the current week.
- 2Identify cost anomaliesRequest a report on any unexpected spikes in costs or latency detected by the platform.
- 3Debug agent execution tracesRetrieve a complete span tree for a specific trace ID to see every tool and retrieval step.
- 4Optimize model costsGet recommendations for alternative models that could lower your monthly operational expenses.
Written from the project's README. Every use case is checked against a quote from it.
How to install Spanlens MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Spanlens MCP in Claude Code
$ claude mcp add --env 'SPANLENS_API_KEY=<YOUR_SPANLENS_API_KEY>' mcp-server -- npx -y @spanlens/mcp-serverInstall Spanlens MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@spanlens/mcp-server"
],
"env": {
"SPANLENS_API_KEY": "<YOUR_SPANLENS_API_KEY>"
}
}
}
}Install Spanlens MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@spanlens/mcp-server"
],
"env": {
"SPANLENS_API_KEY": "<YOUR_SPANLENS_API_KEY>"
}
}
}
}Install Spanlens MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-server","type":"stdio","command":"npx","args":["-y","@spanlens/mcp-server"],"env":{"SPANLENS_API_KEY":"<YOUR_SPANLENS_API_KEY>"}}'Install Spanlens MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@spanlens/mcp-server"
],
"env": {
"SPANLENS_API_KEY": "<YOUR_SPANLENS_API_KEY>"
}
}
}
}Install Spanlens MCP in Codex
$ codex mcp add mcp-server --env 'SPANLENS_API_KEY=<YOUR_SPANLENS_API_KEY>' -- npx -y @spanlens/mcp-serverInstall Spanlens MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-server] command = "npx" args = ["-y", "@spanlens/mcp-server"] [mcp_servers.mcp-server.env] SPANLENS_API_KEY = "<YOUR_SPANLENS_API_KEY>"
Install Spanlens MCP in Gemini CLI
$ gemini mcp add -s user -e 'SPANLENS_API_KEY=<YOUR_SPANLENS_API_KEY>' mcp-server npx -- -y @spanlens/mcp-serverInstall Spanlens MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@spanlens/mcp-server"
],
"env": {
"SPANLENS_API_KEY": "<YOUR_SPANLENS_API_KEY>"
}
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
Spanlens MCP tools 7
Detected from the READMEget_statsquery_requestslist_tracesget_traceget_anomaliesget_savingsget_user_analytics
Configuration
SPANLENS_API_KEYRequiredSecretSpanlens 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.io
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHub@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
{
"mcpServers": {
"spanlens": {
"command": "npx",
"args": ["-y", "@spanlens/mcp-server"],
"env": { "SPANLENS_API_KEY": "sl_live_pub_..." }
}
}
}
{
"mcpServers": {
"spanlens": {
"command": "npx",
"args": ["-y", "@spanlens/mcp-server"],
"env": { "SPANLENS_API_KEY": "sl_live_pub_..." }
}
}
}
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.
Spanlens MCP questions
How do I add Spanlens MCP to Claude Code?
Run claude mcp add --env 'SPANLENS_API_KEY=<YOUR_SPANLENS_API_KEY>' mcp-server -- npx -y @spanlens/mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add Spanlens MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Spanlens MCP provide?
It exposes 7 tools, including get_stats, query_requests, list_traces, get_trace, get_anomalies.
What kind of questions can I ask the agent?
You can ask about LLM spending, cost anomalies, expensive traces, model breakdowns, and recent error calls.
Is it safe to use my API key in my IDE configuration?
Yes, because the server requires public-scope keys which are read-only and cannot trigger LLM proxy spend.
What happens if I use a full-access API key?
The server will refuse to start to prevent security risks associated with plaintext credentials in IDE config files.