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.

Looking to search Userplane documentation from your AI tool instead? See Documentation MCP.

Server URL

https://api.userplane.io/mcp

You need a Userplane account and workspace membership to connect. If you don’t have an account, ask your workspace admin for an invite.

Connect your AI client

Claude

1. Add the Userplane connector

   Open Add Userplane to Claude to prefill Claude’s custom connector form.

2. Open Connectors manually

   If the prefilled form does not open, navigate to the Connectors page in your Claude settings.

   
3. Add a custom connector

   Select Add custom connector.

4. Enter server details

   Enter the connector name Userplane and the MCP server URL:

   https://api.userplane.io/mcp
   

   Select Add.

5. 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.

   
6. Start using it

   Open a new conversation, select the attachments button (the + icon), then select your Userplane connector.

   

Claude Code

Add the server via CLI:

claude mcp add --transport http userplane https://api.userplane.io/mcp

Verify the connection:

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.

See the Claude Code documentation for more details.

The Userplane Claude Code plugin 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.

Codex

The Userplane Codex plugin installs both MCP servers automatically.

codex marketplace add userplanehq/userplane-agent

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

/mcp

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

Cursor

1. Open the command palette

   Press Cmd+Shift+P (or Ctrl+Shift+P on Windows/Linux).

2. Open MCP settings

   Search for Open MCP settings and select it. This opens mcp.json.

3. Configure the server

   Add Userplane to the mcpServers object:

   {
     "mcpServers": {
       "userplane": {
         "url": "https://api.userplane.io/mcp"
       }
     }
   }
   
4. Authorize

   On first use, Cursor opens a browser window for sign-in. Log in and approve access.

See Installing MCP servers in the Cursor documentation for more details.

The Userplane Cursor plugin installs both MCP servers alongside commands, rules, subagents, and skills.

VS Code

1. Create the config file

   Create a .vscode/mcp.json file in your project root.

2. Configure the server

   Add Userplane as a server:

   {
     "servers": {
       "userplane": {
         "type": "http",
         "url": "https://api.userplane.io/mcp"
       }
     }
   }
   
3. Authorize

   On first tool call, VS Code opens a browser window for Userplane sign-in.

See the VS Code documentation for more details.

ChatGPT

1. Open Settings

   Open Settings in ChatGPT.

   
2. Enable Developer Mode

   Under Connectors, enable Developer mode. This is required to register custom MCP servers.

   

   Developer mode is required to add custom MCP connectors. See OpenAI’s Developer Mode guide for details.

3. Open Connectors

   Return to Connectors and select Create. With Developer mode enabled, the custom connector form becomes available.

   
4. 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.

   
5. 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.

   
6. 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.

   

Try it out

1. Verify your connection

   Ask your agent to list your workspaces:

   List my Userplane workspaces.
   

   If you see your workspaces, you’re connected. If you’re prompted to sign in, complete the authorization and try again.

2. Analyze a recording

   Copy a recording URL from the Userplane dashboard and paste it into your AI client. The agent extracts the workspace and recording IDs from the URL and fetches the session data.

   Here's a recording from a customer reporting a checkout issue:
   https://dash.userplane.io/{workspaceId}/recordings/{recordingId}
   What's causing the problem?
   

   Claude

   

   ChatGPT

   
3. 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.

   Show me the full recording for {recordingId} in workspace {workspaceId}.
   

   Interactive viewers render in Claude (desktop and web) and ChatGPT. Other clients display the same data as structured text. See MCP Apps for details.

4. Create a recording link

   Ask your agent to create a recording link for a customer issue.

   Create a recording link for domain {domainId} in workspace {workspaceId}. Reference it as {ticketId}.
   

Tips

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.

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?”

For details on the OAuth 2.1 authentication flow, see Authentication.

Related articles

• Userplane MCP — overview of the workspace MCP server.
• Codex Plugin — bundled skills and MCP servers for Codex.
• Cursor Plugin — bundled commands, rules, skills, and MCP servers for Cursor.
• Claude Code Plugin — bundled slash commands, subagents, skills, and MCP servers for Claude Code.
• Recording Tools — tools for listing, inspecting, and analyzing recordings.
• Recording Link Tools — tools for creating and managing recording links.
• MCP Apps — rich viewers rendered inside your AI client.
• Authentication — OAuth 2.1 flow and permissions.