Span MCP Server

Last updated: October 29, 2026

Span's MCP server connects AI tools such as Claude Code, Claude Desktop, Cursor, and other MCP-compatible clients to your Span data, so you can ask your assistant about engineering metrics, pull requests, issues, people, teams, DORA, meetings, surveys, and AI agent sessions.

Why it matters

You can query Span from the assistant you already work in, under your own login and permissions. Use the MCP server when you want an AI assistant to query Span for you. Use the Knowledge Graph API when you're writing a script or integration directly. Both expose the same data.

How it works

MCP server URL: https://api.span.app/mcp
  • Transport: streamable HTTP.

  • Authorization: OAuth 2.0, or a static bearer token for headless setups.

  • Read access: the server offers tools for discovering and querying Span data. Your assistant picks the right one for your question.

  • Your permissions apply. Every request runs as the signed-in person or the token's owner, and Span's role-based access control applies on top of the OAuth scope.

Data you can ask about:

  • Schema discovery: available assets, fields, relations, dimensions, and metrics

  • Code and pull requests: PRs, reviews, comments, commits, and repositories

  • Projects: issues, epics, and sprints

  • People: per-person data and individual-level metrics

  • Teams: team structure, hierarchy rollups, and team-level metrics

  • DORA: deployments, incidents, and services

  • Meetings: your own calendar meetings over a bounded time range

  • Surveys: aggregate engagement and sentiment data

  • AI agent sessions: agent traces (Claude Code and similar), listed, aggregated, or drilled into

Some data appears only when your organization has it. For example, agent-session data needs AI trace collection.

Setup

Option 1: OAuth (recommended)

Your tool handles the sign-in flow, and you authorize with your Span account in the browser.

Claude Code

claude mcp add --transport http span https://api.span.app/mcp

Then open a Claude session and run /mcp. A browser window opens so you can authorize with your Span account.

Claude Desktop: add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "span": {
      "type": "http",
      "url": "https://api.span.app/mcp"
    }
  }
}

Claude Desktop prompts you to sign in with your Span account on first use.

Cursor: add the server to ~/.cursor/mcp.json (everywhere) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "span": {
      "url": "https://api.span.app/mcp"
    }
  }
}

Then open Customize in the Cursor sidebar, find the span server, and complete the OAuth sign-in in the browser. Cursor discovers the authorization flow and registers its own OAuth client, so you don't need a client ID or secret. Span's tools then appear under Available Tools in chat.

Other MCP clients: point the client at https://api.span.app/mcp. The server publishes OAuth discovery metadata at https://api.span.app/.well-known/oauth-protected-resource/mcp, so any client that follows RFC 9728 discovers the authorization flow automatically.

Option 2: Static bearer token

For headless or shared setups where a browser sign-in isn't possible, send a token as a header on the MCP connection:

Authorization: Bearer <access token>
  • Personal access token: acts with your own permissions. Create one under Settings → Personal → Access Token.

  • Service account token (recommended for shared tools and automation): create the account in Settings → Service Accounts, then use Manage Token in its row menu to generate a token. A service account gets its access from its own settings on that page, not from permission groups. Owners and Admins can manage service accounts by default.

Things to know

  • Access is read-only. OAuth clients connect with the span:read scope, which reads the metrics and records you have access to. The server doesn't offer tools that change Span data.

  • A token sees only what its owner can see. For example, a manager whose permissions cover their own reporting line gets results for that line only, even when they ask about the whole organization. A service account token sees only what that service account can access.

  • Empty results usually mean scope, not an error. Widen the time range or relax filters before assuming a permissions problem.

Troubleshooting

Symptom

Likely cause and fix

Browser sign-in doesn't start

Confirm the client supports HTTP MCP transport and the URL is exactly https://api.span.app/mcp.

401 Unauthorized

Missing, expired, or malformed bearer token. Re-run the OAuth flow or issue a new token.

403 Forbidden

The token lacks permission for the requested data. For a person, check their permission groups. For a service account, check its settings in Settings → Service Accounts.

A data area isn't available

Your organization may not have that data, for example AI trace data for agent sessions.

Empty results

Widen the time range or relax filters.

Related articles

Knowledge Graph API

How to Create a Span API Token

Service Accounts

Roles & Permissions in Span

Ask questions about your Span data from Claude Code or Cursor (/span:ask)

Need help?

Contact your Span account team or reach out to support@span.app.