# mcp-server

This MCP server lets an IDE agent query Spanlens observability data, including LLM spend, traces, errors, and anomalies. Use it when investigating model usage.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 13
- Author: spanlens
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/spanlens/Spanlens/tree/HEAD/packages/mcp-server
- Updated: 2026-10-19
- HTML: https://affpapa.org/en/nevibecode/mcp/spanlens-mcp-server

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `SPANLENS_API_KEY`, `SPANLENS_BASE_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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-server
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add mcp-server --env SPANLENS_API_KEY=<SPANLENS_API_KEY> --env SPANLENS_BASE_URL=<SPANLENS_BASE_URL> -- npx -y @spanlens/mcp-server
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e SPANLENS_API_KEY=<SPANLENS_API_KEY> -e SPANLENS_BASE_URL=<SPANLENS_BASE_URL> mcp-server npx -y @spanlens/mcp-server
```
Replace <…> with your own values

## When to use it
- 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
- 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 trace `abc123…`.

## Similar
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16730
- [labelhead-artist-momentum](https://affpapa.org/en/nevibecode/mcp/labelhead-artist-momentum.md) — MCP server · ★ 107701
- [Agent Skills Search Server](https://affpapa.org/en/nevibecode/mcp/agent-skills-search-server.md) — MCP server · ★ 26673
- [Skyvern](https://affpapa.org/en/nevibecode/mcp/skyvern.md) — MCP server · ★ 23283
- [Nhost](https://affpapa.org/en/nevibecode/mcp/nhost.md) — MCP server · ★ 9369
- [PraisonAI](https://affpapa.org/en/nevibecode/mcp/praisonai.md) — MCP server · ★ 9298

## Other versions with the same name
- [mcp-server · heyputer](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — ★ 43902
- [mcp-server · mapbox](https://affpapa.org/en/nevibecode/mcp/mapbox-mcp-server.md) — ★ 363
- [mcp-server · packmindhub](https://affpapa.org/en/nevibecode/mcp/packmindhub-mcp-server.md) — ★ 319
- [mcp-server · bingowon](https://affpapa.org/en/nevibecode/mcp/bingowon-mcp-server.md) — ★ 121
- [mcp-server · ui5](https://affpapa.org/en/nevibecode/mcp/ui5-mcp-server.md) — ★ 105

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md