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

# Workspace MCP server

> Connect Claude, Cursor or any MCP client to your Puntego workspace and ask about analytics, conversations and the Inbox. Read-only.

The workspace MCP server lets your team ask their own AI assistant about the
guide: *"How many conversations went unanswered this week?"*, *"Find
conversations about SSO"*, *"What's open in the Inbox?"*. It is **read-only**:
nothing it does changes your workspace.

<Note>
  Requires **Growth or higher** and an API key (**Settings → API keys**) with
  `analytics:read`, `transcripts:read` or both. The key is a secret: it reads
  your workspace's data. Give it to people, not to shared files.
</Note>

<h2 id="connect">
  Connect
</h2>

The endpoint is `https://worker.puntego.com/api/v1/mcp`. Send the key as
`Authorization: Bearer <key>`. **Settings → API keys → Connect from Claude /
Cursor** in the dashboard has the same configuration ready to copy.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http puntego https://worker.puntego.com/api/v1/mcp --header "Authorization: Bearer pk_live_YOUR_KEY"
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add it to `claude_desktop_config.json` (it uses the `mcp-remote` bridge, which
    needs Node.js):

    ```json theme={null}
    {
      "mcpServers": {
        "puntego": {
          "args": [
            "-y",
            "mcp-remote",
            "https://worker.puntego.com/api/v1/mcp",
            "--header",
            "Authorization:${AUTH_HEADER}"
          ],
          "command": "npx",
          "env": {
            "AUTH_HEADER": "Bearer pk_live_YOUR_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    Add it to `.cursor/mcp.json` in a project, or `~/.cursor/mcp.json` for every
    project:

    ```json theme={null}
    {
      "mcpServers": {
        "puntego": {
          "headers": {
            "Authorization": "Bearer pk_live_YOUR_KEY"
          },
          "url": "https://worker.puntego.com/api/v1/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

Replace `pk_live_YOUR_KEY` with your key.

<h2 id="tools">
  Tools
</h2>

The server lists only the tools your key may call.

| Tool | Scope | What it returns |
| - | - | - |
| `get_analytics` | `analytics:read` | The Analytics page's numbers for `24h`, `7d`, `30d` (default) or `90d`: conversations, resolved, unanswered, follow-ups, tours, suggestion funnels, stuck-visitor help and a daily series |
| `list_conversations` | `analytics:read` | Conversation summaries, most recent first: when they started and last moved, questions asked, points resolved, whether the guide walked them through, the outcome. No message text. Filters: `since`, `until`, `outcome`; paged with `cursor` |
| `search_conversations` | `transcripts:read` | Conversations whose text contains the words in `query`, most recent match first, with a redacted excerpt |
| `get_conversation` | `transcripts:read` | One conversation's summary and its turns (up to 200), redacted |
| `list_inbox_items` | `analytics:read` | Inbox items (`open` by default): category, status, priority, severity, how often and when. Filters: `status`, `category`, `priority`; paged with `cursor` |
| `get_inbox_item` | `analytics:read` | One Inbox item with its 50 most recent occurrences (when, on which page, in which conversation) |

Time windows (`since`, `until`) default to the last 30 days and may span at
most 90 days.

<h2 id="redaction">
  What text it returns
</h2>

Conversation text is redacted exactly as the [transcript export](/api-reference)
redacts it: each turn is capped at 4,000 characters and common email, phone,
card, IBAN, SSN and credential-in-URL patterns are replaced with `[[PII:…]]`
markers. Pattern redaction reduces exposure; it is not a guarantee that
free-form text holds no personal data.

* **Without `transcripts:read`** the server returns no message text at all:
  conversation summaries only, and Inbox items without their titles and details
  (`text_withheld: true`).
* **Search terms** may not contain contact, payment or credential identifiers:
  a search for one is refused, and every search matches the redacted text only
  (a fragment such as `@example.com` finds nothing), so the search cannot tell
  whether a redacted value appears in a conversation.

<h2 id="protocol">
  Protocol
</h2>

* **Transport:** Streamable HTTP on one endpoint. Every request is a `POST`;
  every reply is a single JSON object (nothing streams). `GET` and `DELETE`
  answer `405`.
* **Versions:** `2026-07-28` (per-request metadata; `server/discover`,
  `tools/list`, `tools/call`, `ping`), and the initialization-based `2025-11-25`,
  `2025-06-18` and `2025-03-26` for clients that still open with `initialize`.
* **Stateless:** the server never issues a session id; each request stands
  alone.
* **Errors:** a missing or invalid key returns `401` with `WWW-Authenticate:
  Bearer`; a key with neither scope returns `mcp/insufficient_scope` (`403`); a
  plan below Growth returns `feature/requires_plan` (`403`). A request from a
  browser origin that is not Puntego's own returns `403`.

<h2 id="limits">
  Limits
</h2>

* **120 requests a minute per key** (`mcp/key-rate-limited`, `429` with
  `Retry-After`), plus the per-IP limit of `/api/v1/*`.

## Next steps

* [Assist API](/assist-api) to start the guide in a visitor's live session from your server.
* [Authentication](/authentication) for API keys and scopes.
* [Analytics](/analytics) for what the numbers mean.


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