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

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

### 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

### 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

* **No workspace filtering** — 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.

#### "Callback URL mismatch" error

This happens when the OAuth redirect URL isn't registered.

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

#### 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