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

# MCP server

> Connect Claude, Cursor, Codex, and other AI agents to Puggy so they can read session evidence directly.

Puggy runs a [Model Context Protocol](https://modelcontextprotocol.io) server. Connect it to your AI coding agent and the agent can open a Puggy session, read its console errors, failed requests, interactions, and bug report, and use that evidence to find and fix the bug, instead of working from a written summary.

## Connect a client

1. [Create an API key](https://docs.puggy.dev/integrations/api-keys.md#create-a-key) with the `sessions:read` scope, and keep it somewhere safe. It's shown only once.
2. Open **API Keys** and select the **Connect an MCP client** tab. Step 1, **Have an active key**, shows a check when you have one.
3. Under **Server URL** and **Auth header**, use the copy buttons if your client asks for these separately. Clients send your key in the `X-Puggy-API-Key` header.
4. Under **Add Puggy to your client**, pick your client: **Claude**, **Cursor**, **Cline**, **Codex**, **Gemini**, or **Kimi**. Copy the configuration it shows.
5. Paste it into your client's MCP settings, replace the placeholder key (for example `pggy_live_your_key_here`) with your own, and restart the client.

![The Connect an MCP client tab: Have an active key, the Server URL and Auth header with copy buttons, and Add Puggy to your client with tabs for Claude, Cursor, Cline, Codex, Gemini, and Kimi above a ready-made configuration](https://mintcdn.com/anoclap/hpVVUQ1W_GXTEu9W/images/console/mcp-connect-light.webp?fit=max\&auto=format\&n=hpVVUQ1W_GXTEu9W\&q=85\&s=d8378160c4aaee26612a6afbdff7ec35)

> [!NOTE]
>
> The **Claude** and **Cline** configurations connect through `npx mcp-remote`, so they need [Node.js](https://nodejs.org) on the machine running the client. Cursor, Codex, Gemini, and Kimi connect to the server URL directly.

## Tools

Every connected client sees the tools below. A tool fails with a scope error if your key doesn't have the scope it needs.

### Session evidence

All of these need `sessions:read`.

| Tool | What it does |
| - | - |
| `resolve_session` | Turns a console session link, public share link, share token, or session ID into an overview: metadata, the bug report, an index of the evidence, and the top errors and failed requests. **Start here.** |
| `get_session_timeline` | One time-ordered stream of console, network, WebSocket, screenshot, and interaction events. Can be limited to a time window or to certain sources. |
| `get_session_evidence` | One kind of evidence, paginated: console errors or warnings, failed requests, screenshots, interactions, WebSocket frames, transcript, or narrative. |
| `get_agent_context` | Your organization, the key's scopes, remaining AI credits, and which features are on. |
| `list_sessions` | Recent sessions, paginated. |
| `search_sessions` | Searches sessions by URL, title, or browser. |
| `get_session` | A session's raw metadata and file summary. |
| `get_session_files` | A session's files, with download links. |
| `get_session_debug_data` | A consolidated debug snapshot. Kept for older setups; prefer `resolve_session` and `get_session_timeline`. |
| `get_session_transcript` | The timestamped audio transcript. Available once a transcript has been generated. |
| `get_session_narrative` | The AI narrative of what happened in the video. |

### Retests

Needs `automation:read` to read and `automation:write` to start or cancel. `get_retest_draft`, `start_retest`, `get_retest`, `list_retests`, and `cancel_retest` let an agent re-run a recorded session against a fix and read the verdict. Retest is in [early access](https://docs.puggy.dev/early-access.md#retest).

### AI generation

`generate_bug_report` and `run_video_intelligence` are listed but need a scope that API keys can't hold, so they don't run from MCP clients today. Generate reports from the console instead.

## Example prompts

* "Open this Puggy session and tell me why checkout fails: https\://…"
* "Find yesterday's sessions on `/settings` and summarise the console errors."
* "Use the Puggy timeline for this session to find the request that failed right before the error, then fix it."

## Troubleshooting

### The client can't connect

* Confirm the key is **Active** on the API Keys page: not revoked or expired.
* Confirm the client sends the `X-Puggy-API-Key` header, and that the server URL matches the one on the **Connect an MCP client** tab.
* Restart the client after changing its configuration.

### A tool returns a scope error

The key is missing the scope that tool needs. Create a new key with the right scopes; you can't add scopes to an existing key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.