Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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:

Claude Desktop

Follow these instructions.

Claude.ai (web)

  1. Go to 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)

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):

On first use, a browser window opens for you to log in.

Both commands above bridge through mcp-remote, which requires Node.js installed (for npx); the package is downloaded automatically on first run.

Microsoft Copilot Studio

Use this to add Birdie as a tool to an agent your organization builds in Microsoft Copilot Studio. Once published, the agent can be used from Microsoft 365 Copilot and Microsoft Teams.

Copilot Studio connects to Birdie with a service account 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 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, 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.

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):

  3. Select Add to agent. Copilot Studio discovers the Birdie tools and lists them on the agent's Tools page.

All Birdie tools are turned on by default. You can turn individual tools off from the Birdie tool's settings page in the agent.

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.

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.

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

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

Last updated