Birdie MCP Server

Birdie's MCP (Model Context Protocol) server connects AI assistants to your Customer Intelligence analytics platform. It lets LLMs query customer feedback, explore trends, and generate Customer Intelligence 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.

How to setup

Prerequisites

• An MCP-compatible client (Claude, Cursor, Claude Code, Claude Desktop, etc.)

• A Birdie account

Client specific setup

• Claude Desktop

• Claude.ai (web)

• Claude Code (CLI)

• Cursor

• Other MCP clients

• Through Gateways and Proxies

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 a couple of tools (get_context and get_taxonomy) that give 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"

Technical Details

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

Claude Desktop

• Follow these instructions.

Claude.ai (web)

1. Go to claude.ai and open Settings > Connectors

2. Click Add Connector and enter the MCP server URL:

https://app-api.birdie.ai/mcp

1. You'll be redirected to the Birdie login page — sign in with your Birdie account

2. Once authenticated, the Birdie tools will appear in your chat

That's it. Claude handles the OAuth flow automatically.

Claude Code (CLI)

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.

Requires Node.js installed (for npx). The mcp-remote package is downloaded automatically on first run.

Cursor

Add this to your Cursor MCP settings (.cursor/mcp.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

If you connect through an MCP gateway or proxy (e.g. Runlayer), 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).

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.

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.

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