Span MCP Server

Span's MCP server connects AI coding tools (Claude Code, Claude Desktop, Cursor, and other MCP-compatible clients) directly to your Span data. Once connected, you can ask your assistant about engineering metrics, pull requests, issues, people, teams, DORA, meetings, surveys, and AI agent sessions, and run built-in report prompts.

The MCP server exposes the same data as the Knowledge Graph API. Use the MCP server when you want an AI assistant to query Span for you; use the Knowledge Graph API when you are writing a script or integration directly.

MCP server URL: https://api.span.app/mcp

The transport is streamable HTTP. Authorization uses OAuth 2.0, with static bearer tokens supported for read-only use (see Authentication).

Connecting

Option 1: OAuth (recommended)

This is the easiest path. 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. It opens a browser window to 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 through your Span account on first use.

Cursor

Add the server to your Cursor MCP config. Use ~/.cursor/mcp.json to make it available everywhere, or .cursor/mcp.json in a 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 when prompted. Cursor discovers the authorization flow automatically and registers its own OAuth client, so you do not need a client ID or secret. Once connected, Span's tools 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 auto-discovers the authorization flow.

Option 2: Static bearer token (read-only)

For headless or shared setups where an interactive browser sign-in is not possible, you can authenticate with a static bearer token. This works for the read tools only; the write tools require OAuth (see Authentication).

• Personal Access Token. Inherits your own permissions. Create one under Settings > Personal > Access Token. See How to Create a Span API Token.

• Service Account (recommended for shared tools and automation). Create it under Settings > Service Accounts and add it to a permission group. See Service Account API permissions and authorization.

Provide the token as a bearer header on the MCP connection:

Authorization: Bearer <access token>

What you can ask

Once connected, your AI tool gets a set of tools for discovering and querying Span data. It selects the right one automatically based on your question, covering:

• 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 capabilities appear only when your organization has the underlying data (for example, agent-session tools require AI trace data).

The server can also update AI trace recommendations (archive, mark done, restore). These are write operations and require OAuth with the span:write scope.

Built-in report prompts

The server ships report prompts for common analyses. Each accepts an optional team and an optional time_range (defaulting to the last 90 days):

• team_health

• dora_summary

• lead_time_report

• investment_balance

• ai_adoption_report

• ai_agent_sessions

Authentication and permissions

Every request to /mcp must include a bearer token. The server enforces access with two OAuth scopes:

All access is scoped to the permissions of the authenticated identity. A token only sees the data its owner or permission group is allowed to see, and Span's role-based access control applies on top of the OAuth scopes. See Roles & Permissions in Span.

Troubleshooting

Related

• Knowledge Graph API (call Span directly): https://help.span.app/articles/9321813047-knowledge-graph-api

• Create a token: How to Create a Span API Token

• Service account permissions: Service Account API permissions and authorization

• Roles and permissions: Roles & Permissions in Span

• Natural-language skill: How to use the Span Claude/Cursor Skill