Zespan MCP server

Zespan provides a hosted MCP (Model Context Protocol) server that lets you query your observability data directly from AI coding tools. Ask questions like “what were the slowest traces in the last hour?” or “run root cause analysis on trace abc123” — without leaving your editor.

Endpoint

https://api.zespan.com/v1/mcp

The server is hosted by Zespan. No local process to run.

Authentication

The MCP server uses personal API keys with the lqtp_ prefix. These are separate from project SDK keys (zsp_) and are scoped to your user account.

Generate a personal API key

Go to Settings → MCP in the Zespan dashboard. Click Generate key, give it a name, and copy the key — it is shown only once.

Client configuration

Claude Desktop
Cursor
Claude Code
Other clients

Open your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the zespan server entry:

{
  "mcpServers": {
    "zespan": {
      "url": "https://api.zespan.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer lqtp_YOUR_PERSONAL_API_KEY"
      }
    }
  }
}

Restart Claude Desktop. You should see Zespan tools listed when you start a new conversation.

Open ~/.cursor/mcp.json (create it if it doesn’t exist) and add:

{
  "mcpServers": {
    "zespan": {
      "url": "https://api.zespan.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer lqtp_YOUR_PERSONAL_API_KEY"
      }
    }
  }
}

Reload Cursor. Zespan tools will be available in Cursor’s agent mode.

Add the server to your Claude Code MCP config (~/.claude/mcp.json):

{
  "mcpServers": {
    "zespan": {
      "url": "https://api.zespan.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer lqtp_YOUR_PERSONAL_API_KEY"
      }
    }
  }
}

Any MCP-compatible client that supports HTTP with custom headers can connect. Use:

URL: https://api.zespan.com/v1/mcp
Header: Authorization: Bearer lqtp_YOUR_PERSONAL_API_KEY

Available tools

The Zespan MCP server exposes 35 tools across seven areas — traces and metrics, prompts, datasets and evaluators, Issues, sessions, retroactive evaluation, and cost. Most are read-only; the write tools (creating a prompt version, moving a label, resolving an Issue, triggering a scoring or retroactive-eval run) are called out as such and enforce the same role permissions as the dashboard. These first nine cover traces and metrics:

Tool	Description
`list_projects`	List all projects your account has access to
`get_project_overview`	Summary of recent activity — event count, error count, avg latency
`query_traces`	Query traces with filters: model, status, time range, limit
`get_trace`	Full detail of a single trace by trace ID
`get_slow_traces`	Find the slowest traces in a given time window
`get_metrics`	Aggregated cost, latency, and token usage grouped by model, hour, or day
`get_errors`	Error breakdown grouped by error code, message, and model
`natural_language_query`	Submit a natural language question about your observability data
`root_cause_analysis`	Run root cause analysis on a failed trace

Prompt management tools

The same MCP server also exposes tools for working with your prompt library, so you can manage prompts without leaving your editor — for example, ask Claude Desktop to draft a new prompt version and promote it once you’re happy.

Tool	Description
List prompts	Lists all prompts in the project, along with each prompt’s labels, type (text or chat), and latest version
Get a prompt	Fetches a prompt by name — optionally at a specific version or label — returning its content, config, resolved content with any nested prompt references composed in, detected `{{variables}}`, labels, tags, and version
Create a prompt	Creates a new prompt, or a new version of an existing prompt, from a name, type, and content, with an optional config, labels, tags, and commit message
Update prompt tags	Replaces a prompt’s tag set
Set a prompt’s label	Moves a label (such as `production`) to a specific version. Promoting to `production` triggers Zespan’s automatic regression check, and moving a protected label — if your organization has configured any — is blocked with a clear error

These tools respect the same permissions as the dashboard and REST API. A personal API key can only do what that user’s role allows — for example, only Admins or Owners can promote to production if your organization has locked that label down — and any protected label your organization has configured is enforced the same way here as everywhere else.

Evaluation & dataset tools

The same MCP server also exposes tools for your datasets and evaluators, so a coding agent can debug a failing trace, inspect an evaluator’s config, or kick off a scoring run without leaving your editor.

Tool	Description
List datasets	Lists datasets in your project, each with item/run counts and its latest scored run
Get a dataset	Fetches a single dataset with its version history
List dataset items	Lists the items in a dataset (paginated)
List dataset runs	Lists a dataset’s runs with scoring status, average score, and coverage
Get a dataset run	Fetches a run with every linked item joined to its input/expected output and result
List evaluators	Lists evaluators configured for your project, with metric key, type, and enabled state
Get an evaluator	Fetches a single evaluator’s full config — system prompt, threshold, score direction
Trigger dataset run scoring	Scores a dataset run’s linked traces against an evaluator
Get an evaluation run	Fetches an evaluation run with its evaluator and per-trace results
Get a trace’s verdict	Returns a trace’s health verdict (failed/degraded/healthy/running), evaluator lens summary, and status counts — optionally with an LLM-generated narrative explanation

Like the prompt tools above, zespan_dataset_run_score respects your role’s permissions — it requires evaluations:manage (Owner, Admin, or Editor). Read-only tools (list/get) are available to any project member.

Issue tools

Issues are the recurring failure patterns Zespan clusters out of failed and degraded traces. Exposing them over MCP means a coding agent can start from “what’s broken” rather than from a trace id you had to find first — and can close the loop by resolving the Issue once it has shipped a fix.

Tool	Description
List Issues	Lists open Issues (excluding resolved and dismissed), most recently seen first, with verdict level, primary span operation, error code, associated prompt, and occurrence count
Get an Issue	Fetches one Issue with its full clustering key, occurrence window, and up to 10 sample traces you can hand straight to the trace or verdict tools
Resolve or dismiss an Issue	Closes an Issue — `resolve` when the pattern was actually fixed, `dismiss` when you just want to stop being shown it. Either can reopen automatically on a fresh occurrence
Generate a remediation suggestion	Runs root-cause analysis across representative sample traces and returns a markdown suggestion — likely underlying cause plus one concrete next step

Resolving or dismissing an Issue requires guardrails:manage (Owner or Admin — Editors cannot). Generating a remediation suggestion requires ai-features:use (Owner, Admin, or Editor). The suggestion is cached per Issue and shared with the dashboard’s Generate suggestion button, so an agent and a teammate see the same text and you’re only billed for one analysis.

Remediation suggestions are advice, not automation. Zespan never opens a pull request, commits to a branch, or otherwise touches your source code — the output is markdown for you or your agent to act on.

Session tools

A multi-turn conversation can go wrong without any single trace looking wrong. These tools give an agent the whole session — the same transcript Zespan’s session-level judge reads.

Tool	Description
List sessions	Lists recent sessions newest first with turn count, total cost, error count, and a preview of the first user message. Filter by end-user id, or to only sessions containing an error
Get a session	Returns a session’s cost/token/duration rollup, its per-turn trace timeline with each turn’s status, and (by default) the ordered turn-by-turn transcript
Get session-level eval scores	Returns the verdicts from evaluators configured with `scope: "session"`, which judge the whole conversation rather than one trace

Retroactive evaluation tools

Retroactive evaluation scores historical traces against an evaluator that wasn’t configured at the time. This is the most useful write tool for a coding agent: right after changing a prompt or swapping a model, it can score the traces the old behavior produced and tell you whether the change is actually an improvement.

Tool	Description
Create a retroactive eval run	Scores historical traces in a time window against an evaluator, with optional operation and model filters. Runs in the background
List retroactive eval runs	Lists this project’s runs newest first, with each run’s status and scored-vs-matched trace progress
Get a retroactive eval run	Returns one run’s full record — status, traces matched and scored, filters, error message if it failed, completion time

Creating a run requires evaluations:manage (Owner, Admin, or Editor). The tool rejects a window whose end is not after its start rather than silently matching zero traces.

Cost tools

Tool	Description
Get cost attribution	Breaks LLM spend down by agent, tool, model, end-user, or operation over a 24h/7d/30d/90d window — total cost, call count, cost per call, average latency, token counts, and error rate per row, ranked by spend

Cost attribution requires the Pro plan or above, exactly like the Costs dashboard. A personal API key does not bypass plan limits.

Example prompts

Once connected, you can ask your AI assistant:

What were the 5 slowest traces in my production project in the last 24 hours?

Run root cause analysis on trace abc123 — why did it fail?

Show me the cost breakdown by model for the last 7 days.

Are there any error spikes in the last hour?

Show me all versions of my support-agent prompt.

Create a new version of my summarizer prompt with this system message, and set it as staging.

Why did trace abc123 fail? Give me the verdict and a plain-English explanation.

Run my "Support QA" dataset's latest run against the Correctness evaluator and show me the results.

What Issues are open in my production project right now, and which one is hitting the most traces?

Read Issue <id>, look at its sample traces, and suggest a fix. Then mark it resolved once I've merged.

Pull up session <id> — show me the full conversation and tell me where it went off the rails.

I just changed the support-agent prompt. Score last week's traces on that operation against the Correctness evaluator and tell me when it's done.

Which of my agents burned the most money in the last 7 days, and what's the cost per call?

Next steps

API keys — manage personal and project API keys
Traces — explore traces in the dashboard
Issues — recurring failure patterns, resolve/dismiss, and remediation suggestions
Sessions — multi-turn conversations and session-level evaluation
Evaluations — evaluators, datasets, and retroactive runs
Prompts — manage prompt versions and labels in the dashboard
Costs — cost attribution and the cost-quality frontier
ZespanPilot — AI copilot built into the Zespan dashboard

​Endpoint

​Authentication

​Generate a personal API key

​Client configuration

​Available tools

​Prompt management tools

​Evaluation & dataset tools

​Issue tools

​Session tools

​Retroactive evaluation tools

​Cost tools

​Example prompts

​Next steps

Endpoint

Authentication

Generate a personal API key

Client configuration

Available tools

Prompt management tools

Evaluation & dataset tools

Issue tools

Session tools

Retroactive evaluation tools

Cost tools

Example prompts

Next steps