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

# Sign in with Bland (OAuth)

> Connect an MCP client to your Bland account by signing in instead of pasting an API key: the flow you see, what the client can do, and what client developers need.

The Bland MCP server accepts two credentials: your organization's API key, or an OAuth 2.1 access token the client gets when you sign in with Bland. With sign-in there's no key to create or paste. The client opens Bland in your browser, you sign in and approve what the client can do, and the client acts as you in the organization you chose.

```text theme={null}
https://api.bland.ai/v1/mcp
```

Clients that already send an API key keep working as before. Nothing on this page changes them.

## Who it's for

* **ChatGPT users.** ChatGPT (apps and connectors, in developer mode) connects to Bland by signing in today.
* **Claude and Claude Code users.** Claude (custom connectors) and Claude Code connect to Bland by signing in today.
* **Client developers** whose client identifies itself with a client ID metadata document. See [For client developers](#for-client-developers).

Clients that only register dynamically (RFC 7591), including Cursor and MCP Inspector, can't sign in yet, because dynamic client registration isn't available on Bland's authorization server. Keep using an [API key](https://docs.bland.ai/integrations/mcp/clients.md) with them. Sign-in will apply to them once dynamic client registration is available.

## What you see when you connect

**1. Add the Bland server in your client**

Give the client the server URL, `https://api.bland.ai/v1/mcp`. The client discovers Bland's authorization server on its own and opens Bland in your browser.

**2. Sign in**

Sign in at `v2.app.bland.ai` with your phone number, Google, or SSO.

**3. Choose an organization**

If you belong to more than one eligible organization, pick the one the client acts in. The connection is scoped to that organization only. Organizations where your role is viewer, or where your account is banned, aren't offered.

**4. Review what the client gets**

The consent screen lists the permissions the client asked for. To make a read-only connection, uncheck **Create and change your agents**. The full list is in [Scopes and consent](#scopes-and-consent).

**5. Use the tools**

The client is connected. Every tool runs as you, in the organization you chose, with the permissions of your role there.

## Scopes and consent

| Consent screen | Scope | What it grants |
| - | - | - |
| Read your Bland workspace: agents, pathways, calls, and settings | `mcp:read` | Every Read tool. |
| Create and change your agents: versions, branches, variables, and deployments | `mcp:write` | Write and Destructive tools that need no narrower scope. Optional: uncheck it for a read-only connection. |
| Place phone calls (billed to this org) | `calls:create` | `create_call`, `send_call`, and `create_batch`. |
| End calls in progress | `calls:stop` | `stop_call` and `stop_batch`. |
| Run evaluations on your agents (uses org credits) | `evals:run` | Runs that spend credits, such as `create_eval_run`, `start_agent_check_run`, and agent test runs. |
| Your name and email | `openid`, `email` | Your identity, so the client can show who's signed in. |
| Stay connected without signing in again | `offline_access` | A refresh token. The client renews its access token without sending you back to the browser. |

Tools declare what they need: Read tools need `mcp:read`, and Write and Destructive tools need `mcp:write`, except tools that place or stop calls (`calls:create`, `calls:stop`) or run billed evaluations (`evals:run`). Discovery advertises only `mcp:read` and `mcp:write`, so when a tool needs one of the others, the server answers with a [step-up](#step-up-consent) challenge. The [tool reference](https://docs.bland.ai/integrations/mcp/tools.md) shows each tool's access level and scope.

### Step-up consent

If a tool needs a scope the connection wasn't granted, for example a write tool on a read-only connection, the server answers `403` with a `WWW-Authenticate` challenge that lists the required scopes. Your client then asks you to grant them. The consent screen pre-checks what you already granted, so you approve only the addition.

## Tokens and disconnecting

* Access tokens are JWTs. Each one lasts 1 hour and is scoped to one organization.
* If you granted **Stay connected without signing in again**, the client holds a refresh token and renews its access on its own.
* To disconnect, remove or disconnect the Bland app in your client. The client revokes its tokens at `https://api.bland.ai/authorization/oauth2/revoke`.
* A connected-apps page in the dashboard, for reviewing and revoking connections, is planned.

Over a sign-in connection, some tools aren't offered:

* The purchase tools (`buy_credits`, `buy_phone_plan`). Buy credits and phone plans in the dashboard, or over an API key connection.
* The generic API passthrough (`bland_api_get`, `call_bland_api`).
* API Reference tools whose endpoints move money, mint keys or sessions, manage members, control live calls, or fall outside the everyday resources. The [tool reference](https://docs.bland.ai/integrations/mcp/tools.md) marks each one **Not offered**.
* The legacy pathway [prompts](https://docs.bland.ai/integrations/mcp/tools.md#prompts-legacy-pathways).

Every other tool behaves as it does with an API key, scoped to the organization you chose and the permissions of your role in it.

## Client support

| Client | Sign in with Bland | What to do |
| - | - | - |
| ChatGPT (apps and connectors, developer mode) | Supported | Add a connector with the URL `https://api.bland.ai/v1/mcp` and sign in when ChatGPT opens Bland. |
| Claude (custom connectors) | Supported | In **Settings → Connectors**, add a custom connector with the URL `https://api.bland.ai/v1/mcp` and sign in when Claude opens Bland. |
| Claude Code | Supported | Run `claude mcp add --transport http bland https://api.bland.ai/v1/mcp`, then `claude mcp login bland`. See [Claude Code](https://docs.bland.ai/integrations/mcp/clients/claude-code.md#sign-in-instead-of-using-a-key). |
| Clients that use client ID metadata documents | Supported | See [For client developers](#for-client-developers). |
| Cursor, MCP Inspector, and other clients that only register dynamically | Not yet available | Use an [API key](https://docs.bland.ai/integrations/mcp/clients.md). Sign-in will apply once dynamic client registration is available. |

## For client developers

Bland's authorization server implements OAuth 2.1 authorization code with PKCE, and the MCP server publishes the discovery documents an MCP client expects.

| Document | URL |
| - | - |
| Protected resource metadata (RFC 9728) | `https://api.bland.ai/.well-known/oauth-protected-resource/v1/mcp` |
| Authorization server metadata (RFC 8414) | `https://api.bland.ai/.well-known/oauth-authorization-server/authorization` |
| OpenID Connect discovery | `https://api.bland.ai/authorization/.well-known/openid-configuration` |

The protected resource document names `https://api.bland.ai/authorization` as the authorization server and `mcp:read` and `mcp:write` as the supported scopes. Bearer tokens are accepted in the `Authorization` header only.

| Endpoint | URL |
| - | - |
| Issuer | `https://api.bland.ai/authorization` |
| Authorization | `https://api.bland.ai/authorization/oauth2/authorize` |
| Token | `https://api.bland.ai/authorization/oauth2/token` |
| Revocation | `https://api.bland.ai/authorization/oauth2/revoke` |

What your client must do:

* **Use PKCE with `S256`.** It's required on every authorization request.
* **Identify itself with a client ID metadata document.** Your `client_id` is an HTTPS URL that serves your client's metadata JSON. The server metadata advertises this with `client_id_metadata_document_supported: true`. Dynamic client registration (RFC 7591) isn't available yet.
* **Send `resource=https://api.bland.ai/v1/mcp`** (RFC 8707) in authorization and token requests. The token is only valid on `/v1/mcp`, not on the REST API.
* **Request the scopes it needs.** `mcp:read` for read tools, `mcp:write` for write tools, `calls:create`, `calls:stop`, or `evals:run` for the tools that declare them, plus `openid`, `email`, and `offline_access` as needed.

How the server responds:

* **No credential:** `401` with `WWW-Authenticate: Bearer realm="bland", resource_metadata="https://api.bland.ai/.well-known/oauth-protected-resource/v1/mcp", scope="mcp:read mcp:write"`. Follow `resource_metadata` to start discovery.
* **Missing scope:** `403` with a `WWW-Authenticate` challenge that lists the required scopes. Re-run authorization requesting them; the consent screen pre-checks what the user already granted.
* **Scopes per tool:** `tools/list` returns each tool's required scopes in `securitySchemes`, with `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint` annotations, so you can request the right scopes up front.

The token endpoint and the UserInfo endpoint are rate limited to 60 requests a minute per IP.

## FAQ

> [accordion] Can I give a client read-only access?
>
> Yes. Uncheck **Create and change your agents** on the consent screen. The client gets `mcp:read` only. If it later calls a write tool, it asks you to grant `mcp:write`.

> [accordion] Can I buy credits or a phone plan over a sign-in connection?
>
> No. `buy_credits` and `buy_phone_plan` aren't offered over OAuth. Buy in the dashboard, or over an API key connection.

> [accordion] Does the token work on the REST API?
>
> No. OAuth tokens are only valid on `/v1/mcp`. Use an API key for the REST API.

> [accordion] Which organization does the client act in?
>
> The one you chose at sign-in. Each access token is scoped to that organization. To work in a different organization, make a new connection and choose it.

> [accordion] My client already uses an API key. Do I need to change anything?
>
> No. A client that sends `Authorization: Bearer org_...` never sees the sign-in flow.

> [accordion] Can I review which apps are connected?
>
> A connected-apps page in the dashboard is planned. Until then, disconnect from the client itself, which revokes its tokens.

## Next steps

> [card] [MCP clients](https://docs.bland.ai/integrations/mcp/clients.md)
>
> API key setup for Claude Code, Cursor, Codex, VS Code, and other clients.

> [card] [Tool reference](https://docs.bland.ai/integrations/mcp/tools.md)
>
> Every tool the server exposes, with its access level.

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.