# Birdie MCP Server Birdie's MCP (Model Context Protocol) server connects AI assistants to your Voice of Customer analytics platform. It lets LLMs query customer feedback, explore trends, and generate VoC reports using natural language. It works with any MCP-compatible client — Claude, ChatGPT, Gemini, Cursor, and more. ### How It Works The MCP server exposes a set of tools that AI assistants can call to interact with your organization's feedback data. When you connect an MCP client to Birdie, the assistant can: * Identify your organization and personalize responses * Explore your taxonomy — areas, opportunities, segments, collections, and feedback sources * Query feedback with filters, grouping, and metrics * Read individual feedback items in detail You sign in with your Birdie account. Each request is scoped to your organization — the assistant only sees your data. ### Available Tools | Tool | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `get_context` | Get your organization's name and description. The assistant calls this first to personalize its responses. | | `get_taxonomy` | Discover your areas, opportunities, segments, collections, and feedback sources. Returns entity names and IDs needed for filtering. | | `get_schema` | Get available fields, metrics, and filter syntax. Returns exact field paths and valid values for querying. | | `query_feedback` | Query feedback with filters, grouping, and metrics. Supports sentiment breakdowns, time-based analysis, text search, and pagination. | | `get_feedback_detail` | Get full details for a specific feedback item — text, sentiment, labels, accounts, custom fields, and metadata. | Some organizations have additional tools enabled depending on their plan and configuration. These may not appear for every account: | Tool | Description | | ------------------------ | --------------------------------------------------------------------------------------------- | | `get_workspaces` | List the workspaces available to you. Returned only when workspaces are enabled for your org. | | `get_workspace_settings` | Get a workspace's behavior preferences, language, enabled modules, and blocklist. | #### Typical Workflow 1. **`get_context`** — learn who the organization is 2. **`get_taxonomy`** — understand the data landscape (what areas, segments, sources exist) 3. **`get_schema`** — discover available metrics, fields, and valid filter values 4. **`query_feedback`** — run queries with filters and grouping 5. **`get_feedback_detail`** — dive into individual feedback items ### Setup #### Prerequisites * An MCP-compatible client (Claude, Cursor, Claude Code, etc.) * A Birdie account #### Claude (claude.ai) 1. Go to [claude.ai](https://claude.ai) and open **Settings > Connectors** 2. Click **Add Connector** and enter the MCP server URL: ``` https://app-api.birdie.ai/mcp ``` 3. You'll be redirected to the Birdie login page — sign in with your Birdie account 4. Once authenticated, the Birdie tools will appear in your chat That's it. Claude handles the OAuth flow automatically. #### Claude Code (CLI) ```bash claude mcp add birdie -- npx -y mcp-remote https://app-api.birdie.ai/mcp ``` On first use, a browser window will open for you to log in with your Birdie account. {% hint style="info" %} Requires Node.js installed (for `npx`). The `mcp-remote` package is downloaded automatically on first run. {% endhint %} #### Cursor Add this to your Cursor MCP settings (`.cursor/mcp.json`): ```json { "mcpServers": { "birdie": { "command": "npx", "args": [ "-y", "mcp-remote", "https://app-api.birdie.ai/mcp" ] } } } ``` On first use, a browser window will open for you to log in. #### Other MCP Clients Any MCP client that supports OAuth 2.1 can connect using the server URL: ``` https://app-api.birdie.ai/mcp ``` The server exposes standard OAuth discovery at `/.well-known/oauth-authorization-server`. #### MCP Gateways & Proxies (e.g. Runlayer) If you connect through an MCP gateway or proxy, configure it as follows: * **Registration:** choose **Dynamic Client Registration** (DCR). Birdie publishes a `registration_endpoint`, so the client registers itself automatically — you do **not** enter a Client ID or Client Secret by hand. If your proxy is set to "Pre-registered Client" and asks for those values, switch it to Dynamic Client Registration. * **Client Secret:** leave it **blank**. Birdie MCP is a **public OAuth client** (`token_endpoint_auth_methods_supported: ["none"]`) and uses PKCE — there is no client secret. * **Scopes:** request `openid profile email offline_access`. * **Callback URL:** the gateway's hosted callback URL must be approved on Birdie's side before login will work (see the hint below). {% hint style="warning" %} Birdie only accepts OAuth callbacks from approved hosts. A hosted gateway's redirect/callback URL must be added to Birdie's allowlist first — otherwise the authorization request is rejected before the login screen appears. Send your gateway's callback URL to your Birdie contact to have its host approved. {% endhint %} ### Authentication Birdie MCP uses **OAuth 2.1 with PKCE** — you sign in with your regular Birdie account. * When you connect, you'll be redirected to the Birdie login page * After signing in, the MCP client receives an access token automatically * Your organization is resolved from your account, so you only see your own data * If you log out of Birdie, the MCP connection will disconnect and you'll need to re-authenticate * Sessions may expire periodically — your client will prompt you to re-authenticate when needed Birdie MCP is a **public OAuth client** and supports **Dynamic Client Registration** (RFC 7591), so MCP clients register themselves automatically — there is no client secret to configure. The scopes used are `openid profile email offline_access`. ### Day-to-Day Usage #### Getting Started Start by asking the assistant to learn about your organization: > *"What's our organization context and what data sources do we have?"* This triggers `get_context` and `get_taxonomy`, giving the assistant the full picture before it runs any queries. #### Example Queries * *"What are the top 5 complaints this month?"* * *"Show me NPS trends over the last 6 months"* * *"Find negative feedback about onboarding from enterprise customers"* * *"Compare satisfaction scores across our data sources"* * *"How many feedbacks did we receive this quarter, grouped by segment?"* * *"What's the CSAT score for our support tickets last month?"* * *"Show me the impact score breakdown by area"* #### Tips * The assistant will call `get_schema` to understand available fields before querying — this is normal * For complex questions, the assistant may make multiple tool calls (schema → query → detail) * All queries are scoped to your organization automatically * Use `get_taxonomy` to discover available IDs for area, opportunity, segment, and collection filters * For large datasets, the assistant can paginate through results automatically * Text search (`text` filter) works across all feedback content ### Known Limitations * **Workspace filtering** — unless workspaces are enabled for your organization, the assistant sees all data in the organization regardless of workspace configuration. * **Session expiry** — sessions may expire periodically depending on token lifetime. Your client will prompt you to re-authenticate when needed. ### Troubleshooting #### Tools disappear or "Authentication required" appears mid-conversation Your session may have expired. Disconnect and reconnect the Birdie connector in your client settings, then sign in again. #### A gateway/proxy asks for a Client ID and Client Secret Birdie MCP uses **Dynamic Client Registration** and is a **public OAuth client**, so there is no client secret to provide. If your proxy (e.g. Runlayer) prompts for these values, its **Registration** is set to "Pre-registered Client" — switch it to **Dynamic Client Registration** and leave **Client Secret** blank. The client will register itself and obtain a Client ID automatically. #### "Callback URL mismatch" or "redirect\_uri not allowed" error This happens when the OAuth redirect URL isn't on Birdie's allowlist of approved callback hosts. * **Claude (claude.ai)**: Should work out of the box. If not, contact your Birdie admin. * **CLI tools (Claude Code, Cursor)**: These use `mcp-remote` which picks a random local port for the callback. Your Birdie admin may need to whitelist additional callback URLs. * **Gateways/proxies (e.g. Runlayer)**: The gateway's hosted callback URL must be added to Birdie's allowlist. Send the exact callback/redirect URL (or paste the URL shown in the error) to your Birdie contact to have its host approved. #### Login succeeds but the connection fails with a `401` The access token is most likely missing the `email` scope. Make sure your client or gateway requests `openid profile email offline_access` — Birdie resolves your account from the email claim, and without it the session can't be authorized. #### Connection drops or intermittent disconnects * Make sure you only have one MCP client connected to Birdie at a time (e.g., don't have both Claude Desktop and Claude web connecting simultaneously) * SSE connections may time out on long idle periods — the client should reconnect automatically --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://ask.birdie.ai/integrations-and-data-ingestion/birdie-mcp-server.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.