> 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, Microsoft Copilot Studio, 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.

Clients that cannot sign in, such as shared agents, automations and some gateways, can [connect with an API key](https://ask.birdie.ai/integrations-and-data-ingestion/birdie-mcp-server/connect-with-an-api-key.md) instead. Microsoft Copilot Studio is one of these: it connects with a service account API key rather than a personal login — see [Microsoft Copilot Studio](#microsoft-copilot-studio).

## 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, Microsoft Copilot Studio, …)

The server URL is the same everywhere:

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

### Claude Desktop

Follow [these instructions](https://ask.birdie.ai/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 %}

### Microsoft Copilot Studio

Use this to add Birdie as a tool to an agent your organization builds in [Microsoft Copilot Studio](https://copilotstudio.microsoft.com). Once published, the agent can be used from Microsoft 365 Copilot and Microsoft Teams.

Copilot Studio connects to Birdie with a [service account](https://ask.birdie.ai/admin-and-settings/users/service-accounts.md) API key rather than a personal Birdie login. Everyone who uses the agent queries Birdie with that service account's access. Read [Service account access](#service-account-access-microsoft-copilot-studio) before you start.

**Before you start**

* A Copilot Studio license (or trial) and permission to create or edit an agent
* A Birdie service account API key (it starts with `brd_`). See step 0 below.
* If the agent will be shared with your organization: a Microsoft 365 or Teams admin who can approve it

**0. Get a service account API key**

Service accounts and their keys are created by Birdie. Ask your Birdie contact for one, as described in [Requesting a service account](https://ask.birdie.ai/admin-and-settings/users/service-accounts.md#requesting-a-service-account), and tell them:

* **What it's for:** for example, "Copilot Studio agent for the support team".
* **Who is responsible for it:** the person to check with before its keys are revoked.
* **What it should see.** For one Copilot agent, the simplest choice is usually **a role on one workspace**.
* **How long the key should last:** never expire, or 30, 90 or 365 days.

The key is shown only once, when Birdie creates it. Store it in a password manager or secret store until you paste it into Copilot Studio in step 2.

{% hint style="warning" %}
Everyone who uses the agent sees what this service account can see. Decide its access before you request the key. Ask for **one key per agent**, so you can revoke one without breaking the others.
{% endhint %}

**1. Add Birdie to your agent**

1. In Copilot Studio, open your agent (or create a new one) and go to the **Tools** page.
2. Select **Add a tool**, then **New tool**, then **Model Context Protocol**.
3. Fill in the server details:
   * **Server name:** `Birdie`
   * **Server description:** the agent uses this text to decide when to call Birdie, so be specific. For example:\
     *Queries the organization's customer feedback and quality data in Birdie: complaints, opportunities and themes, NPS and CSAT trends, sentiment, customer verbatims, and agent quality evaluations. Use it for any question about what customers are saying or how service quality is performing.*
   * **Server URL:** `https://app-api.birdie.ai/mcp`
4. Under **Authentication**, select **API key** and configure:
   * **Type:** Header
   * **Header name:** `Authorization`
5. Select **Create**.

**2. Create the connection**

1. In the **Add tool** dialog, select **Create a new connection**.
2. When asked for the API key, paste your key **with the `Bearer` prefix** (including the space):

   ```
   Bearer brd_<rest-of-your-key>
   ```
3. Select **Add to agent**. Copilot Studio discovers the Birdie tools and lists them on the agent's **Tools** page.

{% hint style="info" %}
All Birdie tools are turned on by default. You can turn individual tools off from the Birdie tool's settings page in the agent.
{% endhint %}

**3. Test it**

In the agent's test pane, ask:

* *"What can you pull from Birdie for this account?"*
* *"What are the top complaints this month?"*

If both return data from your account, the connection works.

**4. Publish to Microsoft 365 Copilot and Teams**

1. Select **Publish**. The agent must be published at least once before anyone, including you, can use it outside Copilot Studio.
2. Go to **Channels** and enable **Teams and Microsoft 365 Copilot**.
3. To make it available to your whole organization, submit it for admin approval. Your admin approves it in the **Teams admin center** (Teams apps > Manage apps) or the **Microsoft 365 admin center** (Integrated apps). Until it's approved, only you can use it.

{% hint style="warning" %}
Copilot Studio creates a Power Platform connector for Birdie behind the scenes. If your organization uses Power Platform data policies (DLP), your Power Platform admin may need to allow it before the agent can call Birdie.
{% 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`.

### With an API key

For clients that send a fixed `Authorization: Bearer` header instead of signing in, see [Connect with an API key](https://ask.birdie.ai/integrations-and-data-ingestion/birdie-mcp-server/connect-with-an-api-key.md).

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

### Service account access (Microsoft Copilot Studio)

Copilot Studio connects with a [service account](https://ask.birdie.ai/admin-and-settings/users/service-accounts.md) API key instead of a personal sign-in, so a few things work differently:

* **Requests don't run as the individual user.** Everyone who uses the agent sees the data the service account can see, regardless of their own Birdie permissions. Share the agent only with people who should have that access.
* **Birdie activity is attributed to the service account**, not to the person asking.
* **The key is a credential.** Store it only in the Copilot Studio connection and your secret store. Don't paste it into chats or documents.
* **When the key expires or is revoked, the agent stops working for everyone** until you update the connection with a new key.

To stop access, an admin can block or remove the service account in **Settings → Users** (takes effect within 5 minutes). To stop one key at once while keeping the others, ask your Birdie contact to revoke it. See [Service accounts](https://ask.birdie.ai/admin-and-settings/users/service-accounts.md) for details.

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

### Copilot Studio: the Model Context Protocol option only opens documentation

The MCP onboarding wizard isn't enabled in your Microsoft tenant yet. Microsoft rolls it out by region and tenant. Check with your Microsoft admin.

### Copilot Studio: the Birdie tool returns a `401`

The connection's API key value is wrong or the key is no longer valid. Check that the value is `Bearer` (with a space) followed by your `brd_` key, and that the header name is exactly `Authorization`. If it still fails, the key may have expired or been revoked, or the service account may be blocked. Ask your Birdie contact for a new key and edit the connection with it.

### Copilot Studio: colleagues can't find the agent in Teams or Microsoft 365 Copilot

Check that the agent was published (not only saved), that the **Teams and Microsoft 365 Copilot** channel is enabled, and that an admin approved it. If your organization blocks custom apps in Teams, an admin has to allow them in the Teams admin center (Teams apps > Setup policies).

### 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
