Skip to main content
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: 
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: 
/.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: 
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: 
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: 
Authorization: Bearer YOUR_API_KEY
X-Breakcold-Organization-Id: YOUR_ORGANIZATION_ID
Codex with an environment variable: 
[mcp_servers.breakcold]
url = "https://mcp.breakcold.com/mcp/v1"
bearer_token_env_var = "BREAKCOLD_MCP_TOKEN"
Direct Streamable HTTP request: 
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.