> For the complete documentation index, see [llms.txt](https://docs.birdie.so/birdie-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.birdie.so/birdie-docs/mcp-server.md). # MCP Server Use the Birdie MCP server to give AI agents access to recordings and debugging data, including transcripts, console logs, network requests, user events, and structured metadata.coming soon.... The Birdie MCP server is built for securing sensitive customer data. Three guarantees shape everything it does — and doesn't do: * **Read-only, always.** The server cannot create, modify, or delete anything. There are no write tools to misuse, no scopes to misconfigure. * **Redacted at the source.** Private content in logs is redacted inside the user's browser, before capture. It never leaves the source, so it can never reach Birdie's servers, your MCP client, or the model — there is nothing to redact downstream because it was never collected. * **Stored as files, never in a database.** Recordings and logs are stored as encrypted objects — on Birdie's storage by default, or on your own bucket with custom storage. Either way, their content never enters a database or search index: Birdie fetches a recording's evidence on demand, per recording, and never indexes, aggregates, or mines what's inside. ### 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 access token**.** Go to [Settings → AI agents & CLI](https://app.birdie.so/settings/ai-agents) and create a new token. Authenticate with: ``` Authorization: Bearer ``` 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:
list_recordings Search and browse recordings using: * text query * ticket ID * email * folder * date
get_metadata Retrieve structured recording context: * recording details * participants * browser and device info * page context * metadata payloads
get_video_transcript * Returns transcript text * Provides WebVTT captions when available
get_console_logs Access console logs with: * timestamps * log levels (`error`, `warning`, `info`, etc.)
get_network_requests Inspect network activity with filters: * status code (`500`, `5xx`) * content type * host
get_repro_steps What the user did, in order. `detail: full` adds the starting context and any errors
get_recording_scenes Get a lightweight visual map of a recording (text only, no images): * scene changes as `{t, score}` (higher score = bigger change) * quiet / static spans * duration and dimensions
get_recording_frames Extract still frames (screenshots) to see the screen: * optional `time_range` to focus (else samples the whole recording) * `max_frames` (default `8`, max `12`), `min_width` (default `1280`) * for visual questions or recordings with no logs
get_recording_diagnostics 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.
{% hint style="info" %} `get_user_events` is the previous name for `get_repro_steps` and still works, so existing agent configs keep running. It appears in the tool list marked deprecated; new integrations should use `get_repro_steps`. {% endhint %}
Why is there no "search all recordings for this error" tool? Tools like that only work if the vendor reads and indexes the content of every recording's logs on their own servers. Birdie never does - your logs aren't in any database we could search, ours included. Instead, find recordings by what Birdie does hold (title, tags, ticket, folder, participants, metadata) with `list_recordings`, then inspect that recording's evidence.
*** ### 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:
ChatGPT 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
Claude 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
Mistral 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
Cursor 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
VSCode 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": [] } ```
Windsurf 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
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