mcp-server · spanlens — Claude Code MCP server: use and install
This MCP server lets an IDE agent query Spanlens observability data, including LLM spend, traces, errors, and anomalies. Use it when investigating model usage.
claude mcp add --env SPANLENS_API_KEY=<SPANLENS_API_KEY> --env SPANLENS_BASE_URL=<SPANLENS_BASE_URL> --transport stdio mcp-server -- npx -y @spanlens/mcp-serverWhat mcp-server does
mcp-server connects an agent to a Spanlens workspace through MCP. Its seven tools cover spend and token summaries, individual request searches, trace discovery, and full span trees. The server also reports detected cost or latency anomalies, suggests model swaps, and breaks usage down by end user.
Set SPANLENS_API_KEY to a sl_live_pub_* credential before starting it. Startup checks the key scope, and a full-access sl_live_* key is rejected because the credential is stored in an IDE configuration file. The package runs with npx -y @spanlens/mcp-server; self-hosted Spanlens instances can use SPANLENS_BASE_URL.
Stats can be grouped by model or provider, while request searches accept filters such as status, user, and time range. The server will not start without a public-scope key, so create that credential before configuring the MCP entry.
What it helps with
- inspect LLM spend by model or provider
- spot unusual cost and latency patterns
- find failed calls for a selected model
- trace an agent run down to its spans
- compare model swaps with projected savings
Example prompts for the agent
- Show our LLM spend for this week, grouped by provider.
- Find recent cost or latency anomalies in Spanlens.
- List failed calls for
gpt-4o, then inspect traceabc123….
How to install mcp-server
Platform CLI
claude mcp add --env SPANLENS_API_KEY=<SPANLENS_API_KEY> --env SPANLENS_BASE_URL=<SPANLENS_BASE_URL> --transport stdio mcp-server -- npx -y @spanlens/mcp-serverReplace <…> with your own values
Platform CLI
codex mcp add mcp-server --env SPANLENS_API_KEY=<SPANLENS_API_KEY> --env SPANLENS_BASE_URL=<SPANLENS_BASE_URL> -- npx -y @spanlens/mcp-serverReplace <…> with your own values
Config file
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@spanlens/mcp-server"
],
"env": {
"SPANLENS_API_KEY": "<SPANLENS_API_KEY>",
"SPANLENS_BASE_URL": "<SPANLENS_BASE_URL>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@spanlens/mcp-server"
],
"env": {
"SPANLENS_API_KEY": "<SPANLENS_API_KEY>",
"SPANLENS_BASE_URL": "<SPANLENS_BASE_URL>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e SPANLENS_API_KEY=<SPANLENS_API_KEY> -e SPANLENS_BASE_URL=<SPANLENS_BASE_URL> mcp-server npx -y @spanlens/mcp-serverReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-server
How do I install mcp-server in Claude Code?
Run claude mcp add mcp-server -e SPANLENS_API_KEY=<SPANLENS_API_KEY> -- npx -y @spanlens/mcp-server. Use a public-scope key.
What does mcp-server do?
It gives an MCP-connected agent read access to Spanlens data about LLM costs, tokens, latency, errors, requests, and agent traces.
Which API key does mcp-server require?
Use a sl_live_pub_* key from the Public Keys section. The server rejects a full sl_live_* key, while the public key cannot call proxy or ingest operations.
Similar MCP servers
All MCP servers for AI and ML →mcp-server by other authors comes first.
