> For the complete documentation index, see [llms.txt](https://ask.birdie.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ask.birdie.ai/integrations-and-data-ingestion/birdie-mcp-server.md).

# Birdie MCP Server

Birdie's MCP (Model Context Protocol) server connects an AI assistant to your Birdie account. You ask a question in plain language and the assistant answers it from your own data — your feedback, your taxonomy, your quality evaluations — instead of from what it happens to know.

It works with any MCP-compatible client: Claude (web, desktop, Claude Code), Cursor, and other clients that support OAuth.

You sign in with your Birdie account, and every request runs as you. The assistant sees exactly the data you would see in the app — no more, no less.

## What you can ask it

The assistant starts each session by reading your organization's context: which Birdie modules you have, which entities exist in your account, and what they mean. Everything below depends on what your organization actually licenses, so a Customer Intelligence-only account will not answer the Frontline Intelligence questions.

**Customer Intelligence (Voice of Customer)**

* *"What are the top complaints this month, and how does that compare to last month?"*
* *"Show me NPS and CSAT trends over the last 6 months, broken down by source."*
* *"Which opportunities are driving negative sentiment in the Checkout area?"*
* *"What are customers actually saying about onboarding?"* — the assistant can read the customer's own words, not just the counts.
* *"What feedback in this area isn't covered by any opportunity yet?"*

**Frontline Intelligence (Quality Assessment)**

* *"How did our BPO teams score against the quality rubric last month?"*
* *"Which criteria do agents fail most often, and on which kinds of contact?"*
* *"Show me the critical cases from last week."*

**Across both**

* *"Put together an executive summary of last quarter for the leadership meeting."*
* *"Why did satisfaction drop in August? Walk me through it."*

Ask follow-up questions the way you would with a colleague. The assistant can chain several lookups to answer one question, and it will tell you which entities and filters it used.

## Getting good answers

* **Start broad, then narrow.** "How is returns doing?" gets a picture; "show me the negative feedback about return shipping costs from enterprise accounts in the last 30 days" gets the detail.
* **Ask for the verbatims.** Counts tell you how big something is; the customer's own words tell you what it is. Ask for examples and the assistant will pull real feedback.
* **Ask it to show the links.** Every entity it mentions can come with a link straight into Birdie, so you can keep working in the app.
* **Contextualize the numbers.** Ask for shares and comparisons ("as a % of total", "vs. the previous quarter") rather than raw counts.
* **Let it look things up.** Before it queries, the assistant checks which fields and values your account actually has. A few tool calls before the answer is normal, not a problem.
* **Ask what it can do.** "What can you pull from Birdie for this account?" is a valid question — the answer reflects your own modules and permissions, which is more reliable than any list in this article.

## Setup

### Prerequisites

* A Birdie account
* An MCP-compatible client (Claude web, Claude Desktop, Claude Code, Cursor, …)

The server URL is the same everywhere:

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

### Claude Desktop

Follow [these instructions](/integrations-and-data-ingestion/birdie-mcp-server/mcp-guide-claude-desktop.md).

### Claude.ai (web)

1. Go to [claude.ai](https://claude.ai) and open **Settings > Connectors**
2. Click **Add Connector** and enter the server URL above
3. You'll be redirected to the Birdie login page — sign in with your Birdie account
4. Once authenticated, the Birdie tools appear in your chat

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 opens for you to log in with your Birdie account.

### 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 opens for you to log in.

{% hint style="info" %}
Both commands above bridge through `mcp-remote`, which requires Node.js installed (for `npx`); the package is downloaded automatically on first run.
{% endhint %}

### Other MCP clients

Any MCP client that supports OAuth 2.1 can connect using the server URL above. The server exposes standard OAuth discovery at `/.well-known/oauth-authorization-server`.

### MCP gateways and 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).

{% 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 and data access

Birdie MCP uses **OAuth 2.1 with PKCE** — you sign in with your regular Birdie account.

* When you connect, you're 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 disconnects 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`.

### What the connection can and cannot do

* **It reads your data.** The connection queries, aggregates and inspects. It does not delete anything, under any configuration.
* **It runs as you.** Whatever your Birdie user cannot see, the assistant cannot see either.
* **Some accounts can also author records** — for example, drafting a coaching note for an agent or opening an initiative — when Birdie has enabled that for the organization. When it's enabled, the assistant shows you exactly what it's about to write and waits for your confirmation before writing it. If you're not sure whether your account has this, ask the assistant or your Birdie contact.
* **Configuring your account happens in the app**, not here. Creating areas, editing taxonomies or changing integrations is done by a person in Birdie.

### Workspaces

If your organization uses workspaces, the assistant works inside one workspace at a time. When you belong to exactly one, it's applied automatically. When you have access to several, the assistant asks you to pick one before it reports any number — if you're ever unsure which workspace an answer covers, ask.

## 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 registers itself and obtains 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.

### The assistant says it can't do something you expected

Two common reasons: your organization doesn't license that module, or your user doesn't have access to that data. Ask the assistant what it can see for your account, and talk to your Birdie contact if something is missing.

### Connection drops or intermittent disconnects

* Keep one MCP client connected to Birdie at a time (e.g. don't have both Claude Desktop and Claude web connected simultaneously)
* Connections may time out on long idle periods — the client should reconnect automatically


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://ask.birdie.ai/integrations-and-data-ingestion/birdie-mcp-server.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.