> For the complete documentation index, see [llms.txt](https://docs.screendesk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.screendesk.io/debug-with-ai/mcp.md).

# MCP

Screendesk MCP gives your AI coding assistant direct, permission-aware access to the evidence captured in Screendesk.

Instead of describing a customer issue from memory, downloading logs, and pasting screenshots into a chat, give the assistant a Screendesk recording or bug report URL. It can inspect the report, connect the user's actions to browser and network evidence, search for similar failures, and help you move from symptom to likely root cause without leaving your coding workflow.

Use Screendesk MCP when you want to investigate interactively in Claude Code, Codex, Cursor, VS Code, or another MCP-compatible assistant.

{% hint style="success" %}
**Fastest path:** connect the endpoint, authorize your workspace, then paste a Screendesk report URL into your assistant.
{% endhint %}

Report context may include workspace member, reporter, customer, comment author, and linked-issue details that the connected user can already access. Exact visitor IP addresses are not returned, and captured credentials, cookies, tokens, signed query parameters, and session identifiers are redacted.

### Connect

#### MCP endpoint

```
https://app.screendesk.io/mcp
```

{% hint style="info" %}
Screendesk MCP is available on Pro and Enterprise plans. Access is bound to one workspace and mirrors the connected user's permissions.
{% endhint %}

{% stepper %}
{% step %}

#### Add Screendesk

Use the endpoint above in your MCP client. Copy a client-specific configuration from [Set up with browser OAuth](#set-up-with-browser-oauth).
{% endstep %}

{% step %}

#### Authorize your workspace

Complete the browser sign-in when your client prompts you.
{% endstep %}

{% step %}

#### Investigate a report

Paste a recording or bug report URL with a concrete debugging objective.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Need repeatable shell commands or CI automation? Use the [Screendesk CLI](/debug-with-ai/cli.md).
{% endhint %}

### Why use Screendesk MCP

Customer-reported bugs often arrive as incomplete descriptions: "checkout failed," "the page froze," or "the button did nothing." The useful evidence is spread across the recording, console, network activity, browser details, and the actions immediately before the failure.

Screendesk MCP makes that evidence available to the assistant already helping you read and change the code. This is useful for:

* **Root-cause investigation** — connect visible behavior to console errors, failed requests, user events, and technical metadata;
* **Reproduction planning** — reconstruct the sequence of actions, environment, and timing that produced the issue;
* **Codebase correlation** — use request URLs, error messages, component names, and stack traces to locate the relevant code;
* **Regression detection** — find other reports with the same normalized error or technical context;
* **Environment comparison** — compare successful and failing sessions across browser, operating system, device, source, and available evidence;
* **Engineering triage** — prepare a better title, labels, assignee, and evidence-backed comment, then write the approved changes back to Screendesk.

### MCP or CLI?

MCP and the Screendesk CLI expose the same permission-aware debugging platform, but they are designed for different ways of working.

| Choose                       | Best for                                                                                                       |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Screendesk MCP**           | Conversational investigation inside an MCP-compatible AI assistant                                             |
| **Screendesk CLI (`sdesk`)** | Explicit terminal commands, scripts, CI, repeatable queries, and agents that work best with command-line tools |

You can use both. For example, use MCP for an exploratory investigation, then use the CLI to repeat the final query across a date range or include it in an engineering workflow.

***

### How it fits into a debugging workflow

#### 1. Start with the customer report

Paste a Screendesk recording or bug report URL into your coding assistant. The assistant resolves the report and sees its description, comments, linked issues, labels, assignees, and which evidence is available.

#### 2. Reconstruct what happened

The assistant can line up:

* the user's clicks and navigation;
* spoken or written context from the transcript;
* screenshots or sampled video frames;
* console errors and warnings;
* failed or unexpected network requests;
* browser, operating system, device, locale, and source details.

Because evidence is timestamped and filterable, the assistant can focus on the moment the failure occurred instead of loading an entire session blindly.

#### 3. Correlate the evidence with your code

Ask the assistant to search your codebase for the error message, request path, component, controller, job, or service implicated by the report. The assistant can combine repository context with Screendesk evidence to explain:

* what the user experienced;
* which request or client-side action failed;
* where the likely implementation path lives;
* what additional evidence would confirm the hypothesis.

#### 4. Check whether the issue is isolated

Search for related reports, summarize recurring errors, or compare several reports. This helps distinguish a one-off environment problem from a broader regression.

#### 5. Fix, verify, and close the loop

After changing the code, use the original action sequence and environment details as a reproduction checklist. With read-write access, the assistant can also propose a triage update or engineering comment and apply it only after your explicit confirmation.

***

### What the assistant can inspect

| Evidence                     | How it helps                                                                                        |
| ---------------------------- | --------------------------------------------------------------------------------------------------- |
| Report details and comments  | Understand the reported symptom, prior investigation, ownership, and linked issues                  |
| User events                  | Reconstruct clicks, navigation, and captured actions before the failure                             |
| Console logs                 | Find exceptions, warnings, resource failures, and client-side state problems                        |
| Network requests             | Inspect failed requests, status codes, hosts, methods, timing, headers, and redacted bodies         |
| Technical metadata           | Identify browser, operating system, device, locale, timezone, network, and source-specific behavior |
| Screenshots and video frames | Verify what was visible at important moments                                                        |
| Transcript                   | Recover user intent and timestamped spoken context                                                  |
| Existing analysis            | Reuse available summaries, sentiment, suggestions, and video analysis                               |
| Related reports              | Find other sessions with shared errors, source URLs, environments, or labels                        |
| Recurring errors             | Rank normalized console and network failures across multiple reports                                |
| Report comparison            | Highlight meaningful differences between two to five reports                                        |

***

### Set up with browser OAuth

Browser OAuth is the recommended setup. Your MCP client opens Screendesk, asks you to choose and authorize a workspace, and stores its own access securely.

{% tabs %}
{% tab title="Claude Code" %}
Run:

```bash
claude mcp add --scope user --transport http screendesk https://app.screendesk.io/mcp
```

Then:

{% stepper %}
{% step %}
Start Claude Code.
{% endstep %}

{% step %}
Run `/mcp`.
{% endstep %}

{% step %}
Select **Screendesk** and authenticate in your browser.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Codex" %}
Add Screendesk to `~/.codex/config.toml`:

```toml
[mcp_servers.screendesk]
url = "https://app.screendesk.io/mcp"
```

Authenticate:

```bash
codex mcp login screendesk
```

Authorize the requested workspace in your browser.

{% hint style="info" %}
For investigations where you want maximum reasoning, you can use a separate Codex profile with `model_reasoning_effort = "xhigh"`.
{% endhint %}
{% endtab %}

{% tab title="Cursor" %}
Open **Cursor Settings → Tools & Integrations**, add a custom MCP server, and use:

```json
{
  "mcpServers": {
    "screendesk": {
      "url": "https://app.screendesk.io/mcp"
    }
  }
}
```

Save the configuration, reload the MCP server if needed, and complete browser authorization when prompted.
{% endtab %}

{% tab title="VS Code" %}
Open the command palette and run **MCP: Add Server**.

1. Select **HTTP**.
2. Enter `https://app.screendesk.io/mcp`.
3. Name the server `screendesk`.

The generated `.vscode/mcp.json` should resemble:

```json
{
  "servers": {
    "screendesk": {
      "url": "https://app.screendesk.io/mcp",
      "type": "http"
    }
  }
}
```

{% endtab %}

{% tab title="Other clients" %}
For clients that support remote Streamable HTTP MCP servers:

```json
{
  "mcpServers": {
    "screendesk": {
      "type": "streamable-http",
      "url": "https://app.screendesk.io/mcp"
    }
  }
}
```

Connect the server and complete browser authorization if the client supports remote MCP OAuth.
{% endtab %}
{% endtabs %}

***

### Use a personal access token

Use a personal access token for headless clients, CI, WSL, or MCP clients that do not support browser OAuth.

{% stepper %}
{% step %}

#### Open developer access settings

Go to **Personal Settings → MCP Access**.
{% endstep %}

{% step %}

#### Create a token

Create a personal access token and enable **MCP**.

Choose:

* **Read-only** for investigation and analysis;
* **Read and write** only when comments or report updates are needed.
  {% endstep %}

{% step %}

#### Copy the token

The token is shown once. Store it in your client's secure credential storage.
{% endstep %}

{% step %}

#### Configure the client

For clients that accept custom headers:

```json
{
  "mcpServers": {
    "screendesk": {
      "type": "streamable-http",
      "url": "https://app.screendesk.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

{% endstep %}
{% endstepper %}

{% hint style="danger" %}
Do not commit personal access tokens to a repository or paste them into prompts. Revoke a token immediately if it may have been exposed.
{% endhint %}

***

### Start an investigation

Give your assistant a Screendesk URL and a concrete objective.

```
This is a Screendesk recording:
https://app.screendesk.io/recordings/REPORT_UUID

Use Screendesk MCP to inspect this recording. Load the relevant context,
including the description, technical metadata, comments, linked issues,
console logs, network requests, screenshots, transcripts, and video frames
when useful.

Reconstruct the user's actions, identify the most likely root cause, correlate
the evidence with this codebase, and propose the next fix. Clearly separate
confirmed evidence from hypotheses.
```

You can also start from a bug report:

```
Use Screendesk MCP to inspect this bug report and explain what failed:
https://app.screendesk.io/bug_reports/REPORT_UUID
```

***

### Available tools

#### Report and evidence tools

| Tool                   | Purpose                                                                                                    |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| `get_report_details`   | Resolve a report and load its details, comments, linked issues, evidence availability, and next-step hints |
| `get_metadata`         | Browser, operating system, device, network, locale, source, and technical metadata                         |
| `get_console_logs`     | Filtered, paginated console output                                                                         |
| `get_network_requests` | Redacted, filtered, paginated network requests                                                             |
| `get_user_events`      | Clicks, navigation, and captured events                                                                    |
| `get_transcript`       | Timestamped transcript segments and transcript status                                                      |
| `get_analysis`         | Existing summaries, sentiment, suggestions, and video analysis                                             |
| `get_screenshots`      | Screenshots and thumbnails as image content                                                                |
| `get_frames`           | Cached or generated video frames at selected timestamps                                                    |

#### Search and cross-report tools

| Tool                         | Purpose                                                                       |
| ---------------------------- | ----------------------------------------------------------------------------- |
| `search_reports`             | Search accessible recordings and bug reports                                  |
| `find_related_reports`       | Find reports with matching errors or technical context and explain each match |
| `summarize_recurring_errors` | Aggregate normalized console and network errors across reports                |
| `compare_reports`            | Compare metadata and evidence availability across two to five reports         |
| `list_folders`               | List accessible folders                                                       |
| `list_members`               | List active workspace members                                                 |

#### Confirmed write tools

| Tool             | Purpose                                                                             |
| ---------------- | ----------------------------------------------------------------------------------- |
| `create_comment` | Add a comment after explicit confirmation                                           |
| `update_report`  | Update title, description, folder, labels, or assignees after explicit confirmation |

{% hint style="warning" %}
Write tools require a read-write grant, explicit confirmation, and a stable idempotency key. They cannot delete reports or change sharing and workspace settings.
{% endhint %}

***

### Example prompts

{% tabs %}
{% tab title="Root cause" %}

```
Inspect this report with Screendesk MCP. Focus on console errors, failed
network requests, and the user actions before the failure. Identify the likely
root cause, show which evidence supports it, and search this repository for the
code path most likely responsible. Separate facts from hypotheses.
```

{% endtab %}

{% tab title="Reproduce" %}

```
Use this Screendesk report to produce a concise reproduction plan. Include the
user's action sequence, relevant timing, browser and operating system, source
URL, and any preconditions suggested by the network or console evidence.
```

{% endtab %}

{% tab title="Related reports" %}

```
Find reports related to this failure. Explain why each report matches and
summarize the shared error signature or technical context.
```

{% endtab %}

{% tab title="Recurring errors" %}

```
Summarize recurring errors from the last seven days. Rank them by affected
reports and include representative Screendesk links.
```

{% endtab %}

{% tab title="Compare reports" %}

```
Compare this failing report with this successful report. Highlight meaningful
differences in browser, operating system, source, device, user actions,
evidence, and captured failures. Rank the differences most likely to explain
the behavior.
```

{% endtab %}

{% tab title="Validate a fix" %}

```
Inspect this Screendesk report and summarize the observable failure as a
verification checklist. After reviewing my code changes, tell me which tests
and manual checks would demonstrate that the reported behavior is fixed.
```

{% endtab %}

{% tab title="Triage" %}

```
Inspect this report and propose a title, labels, assignees, and a short
engineering comment. Show the exact changes and wait for my confirmation
before updating Screendesk.
```

{% endtab %}
{% endtabs %}

***

### Permissions

Every OAuth grant or personal access token is scoped to one Screendesk workspace.

| Access level       | Capabilities                                                          |
| ------------------ | --------------------------------------------------------------------- |
| **MCP disabled**   | The credential cannot use MCP                                         |
| **Read-only**      | Read reports, evidence, media, search results, and analysis           |
| **Read and write** | Read capabilities plus confirmed comments and approved report updates |

Product permissions still apply:

* private folder access is preserved;
* assignment and mention-based access is preserved;
* inaccessible reports return not found;
* watch-only users cannot create developer credentials.

***

### Redaction and auditing

Before network evidence is returned, Screendesk redacts sensitive values such as:

* authorization and proxy authorization headers;
* cookies and set-cookie headers;
* API keys;
* sensitive URL parameters;
* sensitive keys in structured request or response bodies.

Tool calls are audited with operational metadata such as the actor, grant, tool name, status, latency, report identifier, item count, and response size. Evidence bodies and credentials are not copied into audit metadata.

***

### Manage or revoke access

Go to **Personal Settings → MCP Access** to:

* create and review personal access tokens;
* review each token's enabled surfaces and access levels;
* see when a grant was last used;
* revoke a personal access token.

To remove a browser OAuth connection, disconnect Screendesk from the MCP client or revoke the connection from the client that created it.

Personal access token revocation takes effect immediately.

***

### Troubleshooting

<details>

<summary>Why does my client not show Screendesk tools?</summary>

* Confirm the endpoint is `https://app.screendesk.io/mcp`.
* Reload or restart the MCP server in the client.
* Reauthenticate if the authorization expired or was revoked.
* Confirm MCP is enabled on the credential.

</details>

<details>

<summary>Why is access denied after authentication?</summary>

* Confirm you selected the intended workspace.
* Confirm your workspace plan includes MCP.
* Confirm your role can access developer credentials.

</details>

<details>

<summary>Why does a report return not found?</summary>

The report may belong to another workspace or be inside a folder the connected user cannot access.

</details>

<details>

<summary>Why is a write tool rejected?</summary>

Confirm the grant has **Read and write** MCP access. The assistant must also provide explicit confirmation and an idempotency key.

</details>

<details>

<summary>Why does <code>GET /mcp</code> appear in server logs?</summary>

MCP clients may probe the endpoint while negotiating the transport. Screendesk supports authenticated Streamable HTTP requests at the same MCP URL.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.screendesk.io/debug-with-ai/mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.