> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Zespan MCP server

> Connect Claude Desktop, Cursor, or any MCP client to Zespan to query your traces, metrics, and errors in natural language.

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

<Tabs>
  <Tab title="Claude Desktop">
    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:

    ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
    {
      "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.
  </Tab>

  <Tab title="Cursor">
    Open `~/.cursor/mcp.json` (create it if it doesn't exist) and add:

    ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
    {
      "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.
  </Tab>

  <Tab title="Claude Code">
    Add the server to your Claude Code MCP config (`~/.claude/mcp.json`):

    ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
    {
      "mcpServers": {
        "zespan": {
          "url": "https://api.zespan.com/v1/mcp",
          "headers": {
            "Authorization": "Bearer lqtp_YOUR_PERSONAL_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other clients">
    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`
  </Tab>
</Tabs>

## 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](/dashboard/prompts), 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 |

<Note>
  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.
</Note>

## Evaluation & dataset tools

The same MCP server also exposes tools for your [datasets](/dashboard/datasets) and [evaluators](/dashboard/evaluations), 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 |

<Note>
  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.
</Note>

## Issue tools

[Issues](/dashboard/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                            |

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>

## Session tools

A multi-turn conversation can go wrong without any single trace looking wrong. These tools give an agent the whole [session](/dashboard/sessions) — 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"`](/dashboard/sessions#session-level-evaluation), which judge the whole conversation rather than one trace    |

## Retroactive evaluation tools

[Retroactive evaluation](/dashboard/evaluations#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           |

<Note>
  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.
</Note>

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

<Note>
  Cost attribution requires the **Pro** plan or above, exactly like the [Costs dashboard](/dashboard/costs). A personal API key does not bypass plan limits.
</Note>

## 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](/account/api-keys) — manage personal and project API keys
* [Traces](/dashboard/traces) — explore traces in the dashboard
* [Issues](/dashboard/issues) — recurring failure patterns, resolve/dismiss, and remediation suggestions
* [Sessions](/dashboard/sessions) — multi-turn conversations and session-level evaluation
* [Evaluations](/dashboard/evaluations) — evaluators, datasets, and retroactive runs
* [Prompts](/dashboard/prompts) — manage prompt versions and labels in the dashboard
* [Costs](/dashboard/costs) — cost attribution and the cost-quality frontier
* [ZespanPilot](/dashboard/zespanpilot) — AI copilot built into the Zespan dashboard