> ## Documentation Index
> Fetch the complete documentation index at: https://docs.breakcold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate MCP clients with OAuth sign-in or a scoped bearer token.

Breakcold MCP supports two authentication methods: OAuth sign-in and bearer-token access. Use the method that matches how your MCP client runs.

## Choose an authentication method

Use OAuth when the MCP client supports sign-in and should act as the signed-in Breakcold user. This is the recommended option for user-facing clients such as Claude, ChatGPT, Codex, and Microsoft 365 Copilot.

Use a bearer token when the MCP client cannot complete OAuth, or when a service-style agent should use its own scoped access instead of acting as a signed-in user.

Both methods use the same MCP endpoint and the same Breakcold permission checks. Tool calls still enforce organization, workspace, scope, and record-level permissions.

## OAuth sign-in

Use this MCP URL:

```txt theme={null}
https://mcp.breakcold.com/mcp/v1
```

Configure the `/mcp/v1` URL as a protected resource in your MCP client. Breakcold exposes OAuth metadata at the matching protected-resource URL:

```txt theme={null}
/.well-known/oauth-protected-resource/mcp/v1
```

When the client starts sign-in, Breakcold sends the user through WorkOS AuthKit. After sign-in, MCP tool calls run as that Breakcold user.

For Claude Desktop OAuth issues where the browser opens but Claude returns a generic MCP authorization failure, remove the connector and reconnect with the exact MCP URL. If Safari is the default browser, retry with Chrome or another Chromium-based browser, or clear site data for `claude.ai` and the Breakcold AuthKit domain before reconnecting.

OAuth is best when:

* Each user should connect with their own Breakcold account.
* The MCP client can open a browser-based authorization flow.
* You want Breakcold user roles and membership changes to apply automatically.

## Bearer token

Use bearer-token access for clients that ask for an API key, authorization token, bearer key, custom bearer token, or static header.

1. Open Breakcold.
2. Go to **Settings**.
3. Open **API keys** or the MCP application access settings.
4. Create a key with only the scopes the MCP client needs.
5. Limit the key to the workspaces the client should access.
6. Copy the key immediately and store it in the MCP client's secret manager or an environment variable.

Send the key in the `Authorization` header:

```txt theme={null}
Authorization: Bearer YOUR_API_KEY
```

Replace `YOUR_API_KEY` with the key copied from Breakcold. Keep the word `Bearer`, then add one space, then paste the key.

Bearer-token access is best when:

* The MCP client cannot complete OAuth.
* An automation should keep running without a user sign-in session.
* A service-style agent needs a fixed set of scopes and workspace limits.

## Organization selection

For OAuth sign-in, Breakcold can select the organization automatically when the user belongs to exactly one active organization.

If the user belongs to more than one active organization, MCP clients should send:

```txt theme={null}
X-Breakcold-Organization-Id: YOUR_ORGANIZATION_ID
```

Bearer tokens are already tied to the organization and workspace limits chosen when the key was created.

## Examples

Generic header-based MCP client:

```txt theme={null}
Authorization: Bearer YOUR_API_KEY
X-Breakcold-Organization-Id: YOUR_ORGANIZATION_ID
```

Codex with an environment variable:

```toml theme={null}
[mcp_servers.breakcold]
url = "https://mcp.breakcold.com/mcp/v1"
bearer_token_env_var = "BREAKCOLD_MCP_TOKEN"
```

Direct Streamable HTTP request:

```sh theme={null}
curl "https://mcp.breakcold.com/mcp/v1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Common errors

`401 Unauthorized` usually means the token is missing, expired, revoked, copied incorrectly, or sent without the `Bearer ` prefix.

`403 Forbidden` usually means the token or signed-in user does not have the required scope, workspace access, organization membership, or MCP access is not enabled for the organization.

Both 401 and 403 responses include an `X-Request-Id` header. Share this value with Breakcold support if you need help troubleshooting a persistent authorization error.

If OAuth fails before the sign-in page opens, confirm the MCP client supports OAuth protected-resource metadata and is using the exact `/mcp/v1` endpoint. If OAuth succeeds in the browser but Claude still reports an MCP authorization failure, disconnect and reconnect the connector, then retry the flow in Chrome to rule out Safari cookie, content-blocker, or callback state issues.