# mcpspan

mcpspan lets an agent inspect MCP server activity, errors, releases, clients, and sessions. Use it to find failing tools or requests your servers cannot handle.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 23 repo stars
- Author: mcpspan
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/mcpspan/mcpspan/tree/HEAD/packages/mcpspan-mcp
- Updated: 2026-10-28
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/mcpspan

## What it does

Ask an agent to inspect call and error counts, compare releases, review client response times, or find tools that agents requested but the server lacks. It can also show repeated calls and tools exposed to agents but never used. Every tool is read-only.

Connect over HTTP, or run the server as a command with `npx`. The command-based setup needs a read token and Node 20 or newer. Self-hosted command mode requires mcpspan 0.9.0 or newer; address-based access requires version 0.13.0 or newer. Remote access to a self-hosted installation needs HTTPS because each question carries the token.

## Requirements
- Needs: Node.js (commands run via npx)
- Remote server: `https://api.mcpspan.com/mcp`
- Environment variables: `MCPSPAN_READ_TOKEN`, `MCPSPAN_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

1. **Platform CLI: remote server**
```bash
claude mcp add --transport http mcpspan https://api.mcpspan.com/mcp
```

2. **Platform CLI**
```bash
claude mcp add --env MCPSPAN_READ_TOKEN=<MCPSPAN_READ_TOKEN> --env MCPSPAN_URL=<MCPSPAN_URL> --transport stdio mcpspan-mcp -- npx -y mcpspan-mcp
```
Replace <…> with your own values

### Codex

1. **Platform CLI: remote server**
```bash
codex mcp add mcpspan-mcp --url https://api.mcpspan.com/mcp
```

2. **Platform CLI**
```bash
codex mcp add mcpspan-mcp --env MCPSPAN_READ_TOKEN=<MCPSPAN_READ_TOKEN> --env MCPSPAN_URL=<MCPSPAN_URL> -- npx -y mcpspan-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcpspan-mcp": {
            "url": "https://api.mcpspan.com/mcp"
        }
    }
}
```
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcpspan-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "mcpspan-mcp"
            ],
            "env": {
                "MCPSPAN_READ_TOKEN": "<MCPSPAN_READ_TOKEN>",
                "MCPSPAN_URL": "<MCPSPAN_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcpspan-mcp": {
            "type": "http",
            "url": "https://api.mcpspan.com/mcp"
        }
    }
}
```
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcpspan-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "mcpspan-mcp"
            ],
            "env": {
                "MCPSPAN_READ_TOKEN": "<MCPSPAN_READ_TOKEN>",
                "MCPSPAN_URL": "<MCPSPAN_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

1. **Platform CLI: remote server**
```bash
gemini mcp add -t http mcpspan-mcp https://api.mcpspan.com/mcp
```

2. **Platform CLI**
```bash
gemini mcp add -e MCPSPAN_READ_TOKEN=<MCPSPAN_READ_TOKEN> -e MCPSPAN_URL=<MCPSPAN_URL> mcpspan-mcp npx -y mcpspan-mcp
```
Replace <…> with your own values

## When to use it
- spot MCP tools with the most failures
- compare server metrics across releases
- find requests for tools the server does not provide
- inspect failed and repeated calls in a session
- compare error rates across clients

## Example prompts
- Show the most common errors on my MCP server over the last few days.
- Compare my server releases and explain what changed in the metrics.
- Which tools did agents request that my server does not provide?

## Similar
- [Context7](https://affpapa.org/en/nevibecode/mcp/context7.md) — MCP server · 5563 installs
- [Search Google Flights](https://affpapa.org/en/nevibecode/mcp/search-google-flights.md) — MCP server · 2595 installs
- [Math-MCP](https://affpapa.org/en/nevibecode/mcp/math-mcp.md) — MCP server · 5958 installs
- [pipeworx gateway](https://affpapa.org/en/nevibecode/mcp/pipeworx-gateway.md) — MCP server · 419019 installs
- [SparkForge](https://affpapa.org/en/nevibecode/mcp/sparkforge.md) — MCP server · 219896 installs
- [OpenWebSearch](https://affpapa.org/en/nevibecode/mcp/openwebsearch.md) — MCP server · 494 installs

---
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
