> 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/connect-with-an-api-key.md).

# Connect with an API key

By default you connect to the Birdie MCP Server by signing in with your own Birdie account (OAuth). Some setups cannot do that, or should not depend on one person's session:

* a shared assistant or an internal agent your team runs,
* a client or gateway that cannot open a browser sign-in,
* an automation that must keep working when somebody leaves or logs out.

For these, Birdie issues an **API key** that belongs to a [service account](https://ask.birdie.ai/admin-and-settings/users/service-accounts.md) of your organization instead of a person. The client sends the key with every request, and there is no sign-in and no session to expire.

## Getting a key

Your Birdie contact creates the service account and its key. See [Service accounts](https://ask.birdie.ai/admin-and-settings/users/service-accounts.md) for what to ask for, how keys are shown and revoked, and how to manage the account on the Users page.

You receive the key once, so keep it in a password manager or secret store.

## Setup

Every client needs the same two things:

* **Server URL:** `https://app-api.birdie.ai/mcp`
* **Header:** `Authorization: Bearer brd_…` (the word `Bearer`, a space, then your key)

Where a client can read the key from an environment variable, prefer that, and never commit the key to a repository.

{% hint style="warning" %}
**Keep one Birdie connection per client.** Before adding the key, disable or remove any other Birdie connector in the same client, such as the one you sign in to with your Birdie account. With both enabled, you cannot tell which identity answered a question.
{% endhint %}

### Claude Code (CLI)

```bash
claude mcp add --transport http --scope user birdie https://app-api.birdie.ai/mcp \
  --header "Authorization: Bearer brd_…"
```

Or in a project's `.mcp.json`, with the key in the `BIRDIE_API_KEY` environment variable:

```json
{
  "mcpServers": {
    "birdie": {
      "type": "http",
      "url": "https://app-api.birdie.ai/mcp",
      "headers": { "Authorization": "Bearer ${BIRDIE_API_KEY}" }
    }
  }
}
```

Start a new session after changing the configuration. A running session keeps the one it started with. `/mcp` shows whether Birdie is connected.

### Claude Desktop

Claude Desktop reaches remote servers through `mcp-remote`, which needs Node.js installed. Open **Settings > Developer > Edit Config** and add:

```json
{
  "mcpServers": {
    "birdie": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://app-api.birdie.ai/mcp",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer brd_…" }
    }
  }
}
```

Quit Claude Desktop completely and open it again. **Settings > Developer** should show `birdie` as running.

{% hint style="info" %}
If the server fails to start with `spawn npx ENOENT`, Claude Desktop cannot find Node.js. This is common when Node is installed with a version manager such as nvm. Use the full path to `npx` as `command`, for example `/Users/you/.nvm/versions/node/v24.12.0/bin/npx`.
{% endhint %}

### Cursor

`~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "birdie": {
      "url": "https://app-api.birdie.ai/mcp",
      "headers": { "Authorization": "Bearer brd_…" }
    }
  }
}
```

### VS Code (GitHub Copilot)

`.vscode/mcp.json`. VS Code asks for the key once and stores it encrypted:

```json
{
  "inputs": [
    { "type": "promptString", "id": "birdie-key", "description": "Birdie API key", "password": true }
  ],
  "servers": {
    "birdie": {
      "type": "http",
      "url": "https://app-api.birdie.ai/mcp",
      "headers": { "Authorization": "Bearer ${input:birdie-key}" }
    }
  }
}
```

### Codex CLI

`~/.codex/config.toml`, with the key in the `BIRDIE_API_KEY` environment variable:

```toml
[mcp_servers.birdie]
url = "https://app-api.birdie.ai/mcp"
bearer_token_env_var = "BIRDIE_API_KEY"
```

### Gemini CLI

`~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "birdie": {
      "httpUrl": "https://app-api.birdie.ai/mcp",
      "headers": { "Authorization": "Bearer brd_…" }
    }
  }
}
```

### Other clients and gateways

Any MCP client or gateway that can send a fixed `Authorization` header over Streamable HTTP works with the URL and header above.

Claude.ai (web) and ChatGPT connectors cannot send a fixed header. Connect them with your Birdie account as described in [Setup](https://ask.birdie.ai/integrations-and-data-ingestion/birdie-mcp-server.md#setup).

## Check that the key works

```bash
curl -s -X POST https://app-api.birdie.ai/mcp \
  -H "Authorization: Bearer brd_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
```

A working key answers with `"serverInfo":{"name":"Birdie MCP Server", …}`.

## Troubleshooting

### `401` with "Missing or invalid Authorization header"

The header is missing, or its value does not start with `Bearer` (with the space). Check the header name and value in your client's configuration.

### `403` "API key is unknown, revoked or expired"

The key is not valid: mistyped, revoked, expired, or its service account was disabled, blocked or removed. Ask your Birdie contact whether it is still active, or for a new one.

### The client opens a browser sign-in, or reports "Dynamic Client Registration rejected"

The key did not reach Birdie, so the client fell back to signing in. **Do not sign in.** That would connect as you, not as the service account. Fix the header as described in the `401` above. With `mcp-remote`, also delete its saved sign-in state (`~/.mcp-auth`) and restart the client.

### `403` "no access to the requested organization"

A key belongs to one organization. Use the plain URL `https://app-api.birdie.ai/mcp`, not one that names another organization.

### Connected, but answers are empty

The service account can see several workspaces and none at organization level, so each question must name a workspace. Ask the assistant to list the workspaces and pick one, or limit the [service account](https://ask.birdie.ai/admin-and-settings/users/service-accounts.md) to a single workspace.

### Connected, but something you expected is missing

The key sees what its service account's access allows, and nothing more. Ask the assistant what it can see, and talk to your Birdie contact if something is missing.


---

# 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/connect-with-an-api-key.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.
