mcpspan

io.github.mcpspanPublished by GitHub account mcpspanv0.14.0Updated Nov 6, 2026

Ask your agent about your MCP servers: failing tools, releases, clients, sessions.

VerifiedStreamable HTTPWeb executableDeveloper ToolsSecurity & MonitoringData & Analytics

Overview

AI-generated overview

Lets an assistant query mcpspan analytics about your own MCP servers: failing tools, error rates, clients, releases and sessions.

What you can do
  • List the servers an account reports on and get one server's calls, failures, error rate, response times and client mix over a window
  • Rank a server's tools by calls, errors, response time or name, and drill into one tool's failures, refused arguments, answer sizes, definition changes and repeated calls
  • Review recent failed calls, unknown tools agents asked for, and the clients that connected
  • Compare releases side by side, see which tools agents were shown but never called, and inspect sessions call by call
  • Show where agents got stuck, how they recovered, and what they tried next
When to use it
Useful when you run MCP servers instrumented with mcpspan and want to ask an agent in plain language why tools fail, how a release compares with the previous one, or which client or tool is causing trouble, instead of reading the dashboard by hand.
Requirements
Either a remote endpoint at the mcpspan API's /mcp path with OAuth sign-in, or a local process started with npx (Node 20 or newer) using a read token in MCPSPAN_READ_TOKEN; self-hosted installations set MCPSPAN_URL and need mcpspan 0.9.0 or newer for the command, 0.13.0 or newer for the address. A mcpspan account with data to report on.
Before you install
The read token in MCPSPAN_READ_TOKEN is a credential shown once; revoke it in Settings if leaked, and use HTTPS if the agent reaches a self-hosted installation over the internet, since the token travels with every request. OAuth access is granted per app and can be ended under Connected apps. All tools only read; nothing is changed or sent anywhere except your mcpspan.

Installation

In SourceWeft

  1. Open mcpspan in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.mcpspan%2Fmcpspan/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

{
  "mcpServers": {
    "mcpspan": {
      "type": "http",
      "url": "https://api.mcpspan.com/mcp"
    }
  }
}

README

mcpspan-mcp

Ask your AI agent about your MCP servers. Claude Code, Cursor or any other MCP client answers from your mcpspan numbers:

  • Which tools failed most this week, and why?
  • How does 1.4.1 compare with 1.4.0?
  • What do agents ask for that my server does not have?
  • Does Cursor fail more often than Claude?
  • Which tools are agents shown but never call?

It sees what you see in the dashboard and changes nothing. It sends nothing anywhere but your mcpspan.

There are two ways to add it: by address, which needs nothing installed, or as a command your agent starts.

Try it on the demo

No account needed: the live demo answers any token. In Claude Code:

sh
claude mcp add --transport http mcpspan-demo https://demo-api.mcpspan.com/mcp \  --header "Authorization: Bearer demo"

Then ask about the demo's server, Flights: what went wrong in the last day?

By address

The MCP server runs inside mcpspan itself, at /mcp on its API. Add that address to your agent, and the first time it connects it opens mcpspan in your browser: sign in, check which app is asking, and allow it. Nothing to copy.

mcpspan Cloud

The address is https://api.mcpspan.com/mcp.

AgentHow
claude.ai, Claude Desktop, the Claude appsSettings → Connectors → Browse connectors, find mcpspan, and Connect. Or Add custom connector, with the address.
ChatGPTIn its connector settings (developer mode), a new connector with the address, signing in with OAuth.
Claude Codeclaude mcp add --transport http mcpspan https://api.mcpspan.com/mcp, then /mcp in Claude Code to sign in.
CursorIn mcp.json: {"mcpServers": {"mcpspan": {"url": "https://api.mcpspan.com/mcp"}}}
VS CodeIn .vscode/mcp.json: {"servers": {"mcpspan": {"type": "http", "url": "https://api.mcpspan.com/mcp"}}}
OthersWhatever they call a remote, HTTP or Streamable HTTP server, with the address.

The apps you allowed are listed in Settings → Connected apps, where one click disconnects an app and ends its access at once.

An agent that cannot sign in with OAuth can send a read token instead (see Get a token), as a header:

sh
claude mcp add --transport http mcpspan https://api.mcpspan.com/mcp \  --header "Authorization: Bearer mcpspan_read_..."

Self-hosted

The address is your API's, the one your MCP servers report to, with /mcp: http://localhost:6271/mcp on the machine itself. Agents on that machine, such as Claude Code or Cursor, connect as above.

An app that connects from elsewhere, such as claude.ai or ChatGPT, needs that address on HTTPS and reachable from the internet, and the API told where people open your dashboard, since that is where it sends them to allow it: set MCPSPAN_DASHBOARD_URL in .env, for instance https://mcpspan.example.com.

Needs mcpspan 0.13.0 or newer.

As a command

The same tools, started by your agent with npx, reading with a read token. For agents that only start commands, or to keep it on your machine.

Get a token

In mcpspan, open Settings → Read tokens and make one. It is shown once, already filled into the lines below, ready to copy.

mcpspan Cloud

Claude Code:

sh
claude mcp add mcpspan -e MCPSPAN_READ_TOKEN=mcpspan_read_... -- npx -y mcpspan-mcp

Cursor, Claude Desktop, Windsurf and others, in their MCP settings:

json
{  "mcpServers": {    "mcpspan": {      "command": "npx",      "args": ["-y", "mcpspan-mcp"],      "env": { "MCPSPAN_READ_TOKEN": "mcpspan_read_..." }    }  }}

Self-hosted

The same, with the address your MCP servers report to:

sh
claude mcp add mcpspan \  -e MCPSPAN_READ_TOKEN=mcpspan_read_... \  -e MCPSPAN_URL=http://localhost:6271 \  -- npx -y mcpspan-mcp
json
{  "mcpServers": {    "mcpspan": {      "command": "npx",      "args": ["-y", "mcpspan-mcp"],      "env": {        "MCPSPAN_READ_TOKEN": "mcpspan_read_...",        "MCPSPAN_URL": "http://localhost:6271"      }    }  }}

Needs mcpspan 0.9.0 or newer. If the agent reaches your installation over the internet, put HTTPS in front of it: the token travels with every question.

Settings

Variable
MCPSPAN_READ_TOKENThe read token. Required.
MCPSPAN_URLYour installation's API, for self-hosted mcpspan. https://api.mcpspan.com when left out.

Needs Node 20 or newer.

Tools

Every tool only reads. Each takes the server by name or id (left out when the account has one) and a window: days back from now (7 when left out), or from and to.

ToolAnswers
list_serversThe servers the account reports on.
get_overviewCalls, failures, error rate, response times and clients.
list_toolsTools ranked by calls, errors, response time or name.
get_toolOne tool: why it failed, refused arguments, answer sizes, definition changes, repeats, and the call before each failure.
list_errorsThe latest failed calls, with the kind of failure and the message.
list_unknown_toolsTools agents asked for that the server lacks, the closest one it has, and what the agent did next.
list_clientsEach client's calls, error rate and response times.
compare_versionsThe server's releases side by side.
get_tool_listingWhat agents were shown: tools never used, and what their definitions cost.
list_sessionsRecent sessions, with failures and repeated calls.
get_sessionOne session's calls, in order.
get_where_agents_get_lostWhat came of each session, the tools agents got stuck at and what they did next; for one tool, by client.

A token can be revoked at any time under Settings → Read tokens, and an app disconnected under Settings → Connected apps; either loses access at once.

Licence

MIT

Source: packages/mcpspan-mcp/README.md at commit 4b5213f

Tools

12

list_servers

List servers

The MCP servers this mcpspan account reports on, with their names and ids.

Takes no parameters.

get_overview

Overview

Calls, failures, error rate, response times (median and 95th percentile) and the share of each client, for one server over a window.

Parameterstodaysfromclientserver

list_tools

List tools

A server's tools ranked by calls, errors, response time or name, each with its calls, errors, error rate and response times.

Parameterstodaysfromsortlimitclientserver

get_tool

Tool details

Everything recorded about one tool: why its calls failed and the commonest error messages, which arguments the server refused, its parameters, how large its answers are, when its definition changed, how often agents repeated a call, and which call came right before the ones that repeated or failed.

Parameterstodaysfromtoolrequiredserver

list_errors

List failed calls

The most recent failed calls, newest first: which tool, which client, when, what kind of failure (a handler that threw, a tool that answered with an error, refused arguments, an unknown tool) and the error message when the server records them.

Parameterstodaysfromtoollimitclientserver

list_unknown_tools

List unknown tools

Tools that agents asked for but the server does not have: how often, which clients, the closest tool the server does have, and what the agent did next.

Parameterstodaysfromserver

list_clients

List clients

The clients that called the server (Claude, Claude Code, Cursor, VS Code, ChatGPT and others), each with its calls, error rate and response times.

Parameterstodaysfromserver

compare_versions

Compare versions

The server's versions in the window, newest first, each with when it was first seen, its calls, error rate and response times: how a release compares with the one before.

Parameterstodaysfromclientserver

get_tool_listing

What agents are shown

Every tool as agents were shown it when they listed the tools: in how many sessions, how many of those called it, and how large its definition is. Finds tools agents see but never use, and definitions that cost context.

Parameterstodaysfromclientserver

list_sessions

List sessions

Recent sessions (one connection each), newest first, with their calls, failures, tools used and calls an agent repeated with the same arguments.

Parameterstodaysfromtoolwithlimitclientserver

get_where_agents_get_lost

Where agents get lost

Where agents got stuck and what they did about it. A time stuck is a failed tool call and the retries of the same tool straight after it; each ends recovered (the tool then worked, with meanRetries retries on average), wentElsewhere (the agent called something else, insteadMostOften), endedOnIt (the session stopped there, nothing for 30 minutes) or undecided (too recent to tell); looped counts those where a retry repeated the same arguments. Without a tool: every session by the worst that happened in it (clean, recovered, wentElsewhere, looped, endedOnFailure, undecided) and the tools agents got stuck at, worst first. With a tool: that tool's times stuck, as a whole and by client.

Parameterstodaysfromtoolclientserver

get_session

Session

One session's calls in the order the agent made them, with each call's outcome and error.

Parameterstodaysfromserversessionrequired

Version history

4
  1. v0.14.0LatestNov 6, 2026
  2. v0.13.0Oct 29, 2026
  3. v0.12.0Oct 26, 2026
  4. v0.11.0Oct 25, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts