# MCP Server

### Server Address

```
https://app.birdie.so/mcp
```

This is the only URL you need.

AI agents supporting MCP will automatically:

* discover the OAuth configuration
* register a client (Dynamic Client Registration)
* connect to your Birdie workspace

No manual client setup is required.

***

### Authentication

#### OAuth (recommended)

Use OAuth whenever your AI agent supports it.

* No client ID or secret to configure
* No manual setup
* Handled automatically via the MCP endpoint

{% hint style="info" %}
This is the **default and preferred way** to connect.
{% endhint %}

#### Personal Token (fallback)

If your AI agent does not support OAuth, you can use a **Birdie MCP Personal Token**.

Authenticate with:

```
Authorization: Bearer <YOUR_BIRDIE_MCP_PERSONAL_TOKEN>
```

Use this option for:

* headless environments
* CI / scripts
* tools without OAuth support

***

### How it works

Once connected, your AI agent can:

1. Access Birdie recordings
2. Load all associated data (logs, network, transcript, events)
3. Use that context to debug issues or analyze behavior

This removes the need to:

* manually describe bugs
* copy/paste logs
* reproduce issues step by step

***

### Available tools

The Birdie MCP server exposes the following capabilities:

<details>

<summary>list_recordings</summary>

Search and browse recordings using:

* text query
* ticket ID
* email
* folder
* date

</details>

<details>

<summary>get_metadata</summary>

Retrieve structured recording context:

* recording details
* participants
* browser and device info
* page context
* metadata payloads

</details>

<details>

<summary>get_video_transcript</summary>

* Returns transcript text
* Provides WebVTT captions when available

</details>

<details>

<summary>get_console_logs</summary>

Access console logs with:

* timestamps
* log levels (`error`, `warning`, `info`, etc.)

</details>

<details>

<summary>get_network_requests</summary>

Inspect network activity with filters:

* status code (`500`, `5xx`)
* content type
* host

</details>

<details>

<summary>get_user_events</summary>

Read user interactions:

* clicks
* inputs
* navigation events

</details>

<details>

<summary>get_recording_diagnostics</summary>

Returns a full, normalized view of a recording:

* metadata
* transcript
* user steps
* console logs
* network requests
* network summary

Best used when an agent needs full context in a single call.

</details>

***

### Usage pattern

Typical flow:

1. Connect your AI agent to Birdie MCP
2. Provide a recording (link or identifier)
3. Let the agent analyze and debug using MCP tools

***

### Supported clients

We provide setup examples for:

<details>

<summary>ChatGPT</summary>

1. Open ChatGPT Personalisation menu → Apps → Advanced Settings
2. Enable Developer mode
3. Click on Create app
4. Fill in the form with a name (e.g. "Birdie") and a description (e.g. "Search and analyze screen recordings made with Birdie"), then paste this url in the MCP Server URL field:

   `https://app.birdie.so/mcp`
5. Check the acknowledgement checkbox
6. Click Create
7. Authorize the connection with your Birdie account

</details>

<details>

<summary>Claude </summary>

1. Open Claude Desktop → Settings → Connectors
2. Click on Add custom connector
3. Give it a name (e.g. "Birdie") and paste this in Remote MCP server URL field: `https://app.birdie.so/mcp`
4. Click Add
5. Now the connector is present, click on the Connect button
6. Authorize the connection with your Birdie account

</details>

<details>

<summary>Mistral</summary>

1. Open Intelligence menu → Connectors
2. Click on + Add Connector → Custom MCP Connector
3. Give it a name (e.g. "Birdie")
4. Paste this url in the Connector Server field: `https://app.birdie.so/mcp`
5. Select Authentication Method: OAuth2.1 (if not auto discovered already)
6. Click Connect
7. Authorize the connection with your Birdie account

</details>

<details>

<summary>Cursor</summary>

Click here to install in Cursor →  [Install](cursor://anysphere.cursor-deeplink/mcp/install?name=Birdie\&config=eyJ1cmwiOiJodHRwczovL2FwcC5iaXJkaWUuc28vbWNwIn0%3D)

***

Or make a manual installation as follows:

1. Open Cursor Settings (Cmd+Caps+P) → Tools & MCP
2. Click on + New MCP Server
3. Paste this into the mpc.json file:

   ```json
   {
     "mcpServers": {
       "Birdie": {
         "url": "https://app.birdie.so/mcp",
         "headers": {}
       }
     }
   }
   ```
4. Save the file and go back to your MCP Servers
5. Click the Connect button next to your new MCP Server (Birdie)
6. Authorize the connection with your Birdie account

</details>

<details>

<summary>VSCode</summary>

1. Open VSCode Command Palette (Cmd+Caps+P) and type/find >MCP:Add Server
2. Select HTTP option, then paste this server url: `https://app.birdie.so/mcp`

   copiedCould not copy - select text manually instead
3. Enter the name "birdie-mcp"
4. Follow VSCode prompts to authorize connection with your Birdie account
5. Your configguration file should look like this:

   ```json
   {
     "servers": {
       "birdie-mcp": {
         "url": "https://app.birdie.so/mcp",
         "type": "http"
       }
     },
     "inputs": []
   }
   ```

</details>

<details>

<summary>Windsurf</summary>

1. Open Windsurf Command Palette (Cmd+Caps+P) and type/find >MCP Marketplace
2. Click the Cog icon next to Installed MCPs
3. Paste this into mcp\_config.json:

   ```json
   {
     "mcpServers": {
       "Birdie": {
         "serverUrl": "https://app.birdie.so/mcp"
       }
     }
   }
   ```

   copiedCould not copy - select text manually instead
4. Follow Windsurf prompts to open and authorize connection with your Birdie account

</details>

Others: Most MCP-compatible agents can be connected with Birdie using the  server URL `https://app.birdie.so/mcp`

***

### Notes

* OAuth is the preferred authentication method
* Personal Tokens are a fallback option
* Access is scoped to your Birdie permissions
* MCP does not expose anything you cannot already access