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

# Getting Started

> Connect your AI client to Userplane MCP and start analyzing recordings

Connect your AI client to Userplane MCP (the workspace server at `api.userplane.io/mcp`). Authentication is handled automatically via OAuth 2.1 — your client will prompt you to sign in on first use. No API keys required.

<Note>
  Looking to search Userplane documentation from your AI tool instead? See [Documentation
  MCP](/integrations/mcp-docs).
</Note>

## Server URL

```
https://api.userplane.io/mcp
```

<Info>
  You need a Userplane account and workspace membership to connect. If you don't have an account,
  ask your workspace admin for an invite.
</Info>

## Connect your AI client

<Tabs>
  <Tab title="Claude">
    <Steps>
      <Step title="Add the Userplane connector">
        Open [Add Userplane to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector\&connectorName=Userplane\&connectorUrl=https://api.userplane.io/mcp) to prefill Claude's custom connector form.
      </Step>

      <Step title="Open Connectors manually">
        If the prefilled form does not open, navigate to the **Connectors** page in your [Claude settings](https://claude.ai/settings).

        <Frame caption="Claude connector settings">
          <img src="https://mintcdn.com/userplane/q948NEPnf1eM8DIT/media/mcp/claude/oauth/connector-settings.png?fit=max&auto=format&n=q948NEPnf1eM8DIT&q=85&s=bb9c28d973a5527b8d73c93aa8fdb74b" width="1920" height="957" data-path="media/mcp/claude/oauth/connector-settings.png" />
        </Frame>
      </Step>

      <Step title="Add a custom connector">
        Select **Add custom connector**.
      </Step>

      <Step title="Enter server details">
        Enter the connector name `Userplane` and the MCP server URL:

        ```
        https://api.userplane.io/mcp
        ```

        Select **Add**.
      </Step>

      <Step title="Authorize">
        On first use, Claude opens a browser window for Userplane sign-in. Log in with your credentials and click **Allow** on the consent screen.

        <Frame caption="Authorization approved">
          <img src="https://mintcdn.com/userplane/q948NEPnf1eM8DIT/media/mcp/claude/oauth/consent-screen-approved.png?fit=max&auto=format&n=q948NEPnf1eM8DIT&q=85&s=b82b846fd3f0edf9ea2a17f062e99aba" width="1920" height="956" data-path="media/mcp/claude/oauth/consent-screen-approved.png" />
        </Frame>
      </Step>

      <Step title="Start using it">
        Open a new conversation, select the attachments button (the **+** icon), then select your Userplane connector.

        <Frame caption="Userplane connector ready in Claude">
          <img src="https://mintcdn.com/userplane/q948NEPnf1eM8DIT/media/mcp/claude/oauth/post-connect.png?fit=max&auto=format&n=q948NEPnf1eM8DIT&q=85&s=c69d820e6a539d386b14959bbdb74c91" width="1920" height="958" data-path="media/mcp/claude/oauth/post-connect.png" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code">
    Add the server via CLI:

    ```bash theme={null}
    claude mcp add --transport http userplane https://api.userplane.io/mcp
    ```

    Verify the connection:

    ```bash theme={null}
    claude mcp list
    ```

    The `userplane` server should appear in the list. On first tool call, Claude Code opens a browser window for Userplane sign-in.

    <Note>
      See the [Claude Code documentation](https://code.claude.com/docs/en/mcp#installing-mcp-servers) for more details.
    </Note>

    <Tip>
      The [Userplane Claude Code plugin](/integrations/claude-code) installs both MCP servers
      automatically alongside 18 skills and 4 slash commands. If you're using Claude Code,
      the plugin is the fastest setup path.
    </Tip>
  </Tab>

  <Tab title="Codex">
    The [Userplane Codex plugin](/integrations/codex) installs both MCP servers automatically.

    ```bash theme={null}
    codex marketplace add userplanehq/userplane-agent
    ```

    Then open `/plugins` in Codex and install `userplane`. Verify the servers with:

    ```text theme={null}
    /mcp
    ```

    You should see `userplane-workspace` and `userplane-docs`. On first workspace tool call, Codex opens a browser window for Userplane sign-in.
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Open the command palette">
        Press `Cmd+Shift+P` (or `Ctrl+Shift+P` on Windows/Linux).
      </Step>

      <Step title="Open MCP settings">
        Search for **Open MCP settings** and select it. This opens `mcp.json`.
      </Step>

      <Step title="Configure the server">
        Add Userplane to the `mcpServers` object:

        ```json theme={null}
        {
          "mcpServers": {
            "userplane": {
              "url": "https://api.userplane.io/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Authorize">
        On first use, Cursor opens a browser window for sign-in. Log in and approve access.
      </Step>
    </Steps>

    <Note>
      See [Installing MCP servers](https://cursor.com/docs#installing-mcp-servers) in the Cursor documentation for more details.
    </Note>

    <Tip>
      The [Userplane Cursor plugin](/integrations/cursor) installs both MCP servers alongside
      commands, rules, subagents, and skills.
    </Tip>
  </Tab>

  <Tab title="VS Code">
    <Steps>
      <Step title="Create the config file">
        Create a `.vscode/mcp.json` file in your project root.
      </Step>

      <Step title="Configure the server">
        Add Userplane as a server:

        ```json theme={null}
        {
          "servers": {
            "userplane": {
              "type": "http",
              "url": "https://api.userplane.io/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Authorize">
        On first tool call, VS Code opens a browser window for Userplane sign-in.
      </Step>
    </Steps>

    <Note>
      See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for more details.
    </Note>
  </Tab>

  <Tab title="ChatGPT">
    <Steps>
      <Step title="Open Settings">
        Open **Settings** in ChatGPT.

        <Frame caption="ChatGPT settings">
          <img src="https://mintcdn.com/userplane/ruu7f4FXnw5Qs5W2/media/mcp/chatgpt/oauth/settings.png?fit=max&auto=format&n=ruu7f4FXnw5Qs5W2&q=85&s=3f151109c117180b23b04e0cb107da0d" width="2940" height="1664" data-path="media/mcp/chatgpt/oauth/settings.png" />
        </Frame>
      </Step>

      <Step title="Enable Developer Mode">
        Under **Connectors**, enable **Developer mode**. This is required to register custom MCP servers.

        <Frame caption="Enable Developer mode in ChatGPT">
          <img src="https://mintcdn.com/userplane/ruu7f4FXnw5Qs5W2/media/mcp/chatgpt/oauth/developer-mode.png?fit=max&auto=format&n=ruu7f4FXnw5Qs5W2&q=85&s=e3d2721f69408ead5e62d1fa3d342c00" width="2940" height="1662" data-path="media/mcp/chatgpt/oauth/developer-mode.png" />
        </Frame>

        <Note>
          Developer mode is required to add custom MCP connectors. See [OpenAI's Developer Mode guide](https://developers.openai.com/api/docs/guides/developer-mode) for details.
        </Note>
      </Step>

      <Step title="Open Connectors">
        Return to **Connectors** and select **Create**. With Developer mode enabled, the custom connector form becomes available.

        <Frame caption="Connectors with no custom servers yet">
          <img src="https://mintcdn.com/userplane/ruu7f4FXnw5Qs5W2/media/mcp/chatgpt/oauth/connectors-empty.png?fit=max&auto=format&n=ruu7f4FXnw5Qs5W2&q=85&s=bf83ff1f8e44209a7a2f9ccbac83792e" width="2940" height="1664" data-path="media/mcp/chatgpt/oauth/connectors-empty.png" />
        </Frame>
      </Step>

      <Step title="Add the Userplane MCP server">
        Enter a name (e.g., `userplane`) and the MCP server URL:

        ```
        https://api.userplane.io/mcp
        ```

        Select **Create** to register the connector.

        <Frame caption="Add the Userplane MCP server URL">
          <img src="https://mintcdn.com/userplane/ruu7f4FXnw5Qs5W2/media/mcp/chatgpt/oauth/add-mcp-url.png?fit=max&auto=format&n=ruu7f4FXnw5Qs5W2&q=85&s=46e922c09e7ce42c3aeac34dba6b59c8" width="2940" height="1662" data-path="media/mcp/chatgpt/oauth/add-mcp-url.png" />
        </Frame>
      </Step>

      <Step title="Authorize">
        On first use, ChatGPT opens a browser window for Userplane sign-in. Log in with your credentials and click **Allow** on the consent screen.

        <Frame caption="Authorize the Userplane connector">
          <img src="https://mintcdn.com/userplane/ruu7f4FXnw5Qs5W2/media/mcp/chatgpt/oauth/consent-screen.png?fit=max&auto=format&n=ruu7f4FXnw5Qs5W2&q=85&s=d3d94421bb89840fced981a9aa393d5d" width="2940" height="1662" data-path="media/mcp/chatgpt/oauth/consent-screen.png" />
        </Frame>
      </Step>

      <Step title="Start using it">
        The Userplane connector appears under your enabled apps in ChatGPT. Start a new conversation and reference a recording URL or ask the agent to list your workspaces.

        <Frame caption="Userplane connector ready in ChatGPT">
          <img src="https://mintcdn.com/userplane/ruu7f4FXnw5Qs5W2/media/mcp/chatgpt/oauth/post-connect.png?fit=max&auto=format&n=ruu7f4FXnw5Qs5W2&q=85&s=88d0f2fa1488f28394f7be9db400e235" width="2940" height="1662" data-path="media/mcp/chatgpt/oauth/post-connect.png" />
        </Frame>
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Try it out

<Steps>
  <Step title="Verify your connection">
    Ask your agent to list your workspaces:

    <CodeGroup>
      ```text theme={null}
      List my Userplane workspaces.
      ```
    </CodeGroup>

    If you see your workspaces, you're connected. If you're prompted to sign in, complete the authorization and try again.
  </Step>

  <Step title="Analyze a recording">
    Copy a recording URL from the [Userplane dashboard](https://dash.userplane.io) and paste it into your AI client. The agent extracts the workspace and recording IDs from the URL and fetches the session data.

    <CodeGroup>
      ```text theme={null}
      Here's a recording from a customer reporting a checkout issue:
      https://dash.userplane.io/{workspaceId}/recordings/{recordingId}
      What's causing the problem?
      ```
    </CodeGroup>

    <Tabs>
      <Tab title="Claude">
        <Frame caption="Root cause analysis in Claude">
          <img src="https://mintcdn.com/userplane/q948NEPnf1eM8DIT/media/mcp/claude/tools/root-cause-analysis.png?fit=max&auto=format&n=q948NEPnf1eM8DIT&q=85&s=bb29e43158ab985c29415e69c2866fcb" width="1920" height="957" data-path="media/mcp/claude/tools/root-cause-analysis.png" />
        </Frame>
      </Tab>

      <Tab title="ChatGPT">
        <Frame caption="Root cause analysis in ChatGPT">
          <img src="https://mintcdn.com/userplane/ruu7f4FXnw5Qs5W2/media/mcp/chatgpt/tools/root-cause-analysis.png?fit=max&auto=format&n=ruu7f4FXnw5Qs5W2&q=85&s=da8f7800c8f298471fd69f5162a3ab0f" width="2940" height="1662" data-path="media/mcp/chatgpt/tools/root-cause-analysis.png" />
        </Frame>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Explore interactive viewers">
    Ask your agent to show a recording. In Claude and ChatGPT, this opens an interactive viewer with video playback, console logs, network requests, and user actions.

    <CodeGroup>
      ```text theme={null}
      Show me the full recording for {recordingId} in workspace {workspaceId}.
      ```
    </CodeGroup>

    <Note>
      Interactive viewers render in Claude (desktop and web) and ChatGPT. Other clients display the same data as structured text. See [MCP Apps](/integrations/mcp-apps) for details.
    </Note>
  </Step>

  <Step title="Create a recording link">
    Ask your agent to create a recording link for a customer issue.

    <CodeGroup>
      ```text theme={null}
      Create a recording link for domain {domainId} in workspace {workspaceId}. Reference it as {ticketId}.
      ```
    </CodeGroup>
  </Step>
</Steps>

## Tips

<Tip>
  Agents work best when you provide specific recording IDs or dashboard URLs. Copy the URL directly
  from your browser when viewing a recording in the dashboard.
</Tip>

<Tip>
  You can chain requests in a single conversation. Start with "Show me the recording" and follow up
  with "Now focus on the network errors" or "What did the user do right before the error?"
</Tip>

<Tip>
  For details on the OAuth 2.1 authentication flow, see
  [Authentication](/integrations/mcp-authentication).
</Tip>

## Related articles

* [Userplane MCP](/integrations/mcp-workspace) — overview of the workspace MCP server.
* [Codex Plugin](/integrations/codex) — bundled skills and MCP servers for Codex.
* [Cursor Plugin](/integrations/cursor) — bundled commands, rules, skills, and MCP servers for Cursor.
* [Claude Code Plugin](/integrations/claude-code) — bundled slash commands, subagents, skills, and MCP servers for Claude Code.
* [Recording Tools](/integrations/mcp-tools-recordings) — tools for listing, inspecting, and analyzing recordings.
* [Recording Link Tools](/integrations/mcp-tools-links) — tools for creating and managing recording links.
* [MCP Apps](/integrations/mcp-apps) — rich viewers rendered inside your AI client.
* [Authentication](/integrations/mcp-authentication) — OAuth 2.1 flow and permissions.