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

# Bland MCP Server

> Connect coding agents and compatible personal AI agents to your Bland account over MCP.

The Bland MCP server lets any AI agent work with your Bland account through natural language: build, version, and publish Bland Agents, place and inspect calls, send texts, query analytics, run evals, and search the Bland docs. Tools for legacy pathways are still available.

It's a remote [Model Context Protocol](https://modelcontextprotocol.io) server hosted by Bland. There's nothing to run locally: point your client at the endpoint, sign in with Bland or use your API key, and your agent has the full toolset.

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

## Which path is yours?

> [!NOTE]
>
> **Personal AI agent (Grok Bot, Meta Muse, OpenClaw, Instinct, Poke, or similar) asked to integrate with Bland?** Go straight to [Personal AI Agents](https://docs.bland.ai/integrations/mcp/personal-agents.md). The rest of this page is for developers and coding agents.

> [card] [I'm building voice agents from a coding agent](https://docs.bland.ai/integrations/mcp/norm.md)
>
> Install the Norm plugin (`norm@bland`) for Bland Agents. It bundles this server with Bland Agents skills and `/norm:*` commands on supported hosts. Other clients, or the server alone, are on the [MCP clients](https://docs.bland.ai/integrations/mcp/clients.md) page.

> [card] [I want my personal AI agent to have a phone](https://docs.bland.ai/integrations/mcp/personal-agents.md)
>
> Setup guides and compatibility requirements for Grok Bot, Meta Muse, OpenClaw, Instinct, and Poke. Connect through MCP or REST and get a dedicated number on the Agent Phone Plan.

## How it works

* **Transport:** Streamable HTTP (the current MCP standard). The server is stateless, so there are no sessions to manage and any request can hit any node.
* **Authentication:** [sign in with Bland](https://docs.bland.ai/integrations/mcp/oauth.md) (OAuth; ChatGPT, Claude, and Claude Code today, other clients once dynamic client registration is available), or a full-access Bland API key in the `Authorization` header (`Bearer org_...`), which works with every client. [Restricted keys](https://docs.bland.ai/api-v1/post/keys-create.md#restricted-keys) can't connect. Either way, one organization scopes every tool: an agent connected to your org sees only that org's calls, pathways, and agents. Get a key from the [dashboard](https://app.bland.ai/dashboard/settings), or let an agent obtain its own through the [Agent onboarding API](https://docs.bland.ai/platform/connect-your-agent.md).
* **Rate limits:** 120 requests per minute per organization.
* **Safety:** every tool carries read-only and destructive annotations, so well-behaved clients ask before the agent does anything with side effects (like placing a real phone call). The server doesn't ask for confirmation itself, so keep your client's tool-approval prompts on.

## Discovering the server from a 401

A request that reaches `/v1/mcp` with no credential gets a `401` that tells the client what to do next. Clients that already send a valid `Authorization` header never see it. Two pieces:

* A `WWW-Authenticate` header (RFC 6750):

  ```text theme={null}
  WWW-Authenticate: Bearer realm="bland", resource_metadata="https://api.bland.ai/.well-known/oauth-protected-resource/v1/mcp", scope="mcp:read mcp:write"
  ```

  A credential that was refused gets `error="invalid_token"` on the same header.

* A JSON-RPC error body whose `error.message` and `error.data` name the header to send, where a human gets a key, and any self-serve signup flows an agent can run on its own: currently [headless onboarding](https://docs.bland.ai/platform/agent-headless-onboarding.md) and the [device-code flow](https://docs.bland.ai/platform/connect-your-agent.md). Each is listed only while it's enabled.

Which piece a client uses depends on what it supports:

* **OAuth clients** follow `resource_metadata` to the protected resource document (RFC 9728). It names the authorization server, `https://api.bland.ai/authorization`, and the scopes `mcp:read` and `mcp:write`. The authorization server's own metadata is at `https://api.bland.ai/.well-known/oauth-authorization-server/authorization` and `https://api.bland.ai/authorization/.well-known/openid-configuration`. From there the client runs the flow on [Sign in with Bland](https://docs.bland.ai/integrations/mcp/oauth.md). Clients that only register dynamically can't complete it yet and need an API key.
* **Agents with no key** read the body, pick a signup flow, obtain their own key, and retry the same MCP call.

## What your agent can do

| Category | Highlights |
| - | - |
| **Agents** | Full lifecycle for the Bland Agents platform: create, version, branch, publish to staging, promote to production, manage environment variables. For guided builds, use the [Norm plugin](https://docs.bland.ai/integrations/mcp/norm.md). |
| **Calls** | Place an outbound call (`create_call`), wait for it to finish (`wait_for_call`), stop it (`stop_call`), and fetch its transcript, recording, and summary (`get_call_log`). Pick a voice from Bland's curated set (`list_voices`). |
| **Analytics** | Structured call-analytics queries with grouping, filters, and time ranges (`query_analytics`). |
| **Evals** | List and inspect LLM judges, kick off eval runs over batches of calls. |
| **Docs** | Search and read docs.bland.ai from inside the session (`search_bland_docs`, `get_bland_doc`). |
| **Pathways (Legacy)** | Compile-check a pathway graph before saving (`validate_pathway`), fetch the authoritative schema (`get_pathway_schema`), and get deep node/edge semantics (`get_pathway_context`). |
| **API Reference tools** | One tool per [API Reference](https://docs.bland.ai/api-v1/post/calls.md) page, such as `send_call` for every Send Call field, `send_sms`, and the knowledge base, number, and evals endpoints. |
| **Full API reach** | Over an API key connection, anything else: `bland_api_get` for any GET endpoint, `call_bland_api` for any mutating endpoint. |

See the full [tool reference](https://docs.bland.ai/integrations/mcp/tools.md).

Over an API key connection, the server also ships MCP **prompts** for legacy pathways: `bland_pathways`, `build_pathway`, and `edit_pathway`. They appear as slash commands in clients that support them (like Claude Code). For Bland Agents, use the [Norm plugin](https://docs.bland.ai/integrations/mcp/norm.md) instead.

## One endpoint, three MCP surfaces

Bland has three MCP-related surfaces. If you're unsure, use the first one.

| Surface | What it is | When to use it |
| - | - | - |
| `https://api.bland.ai/v1/mcp` | **This server.** Remote, account-scoped, full toolset. | Building on Bland with an AI agent that signs in with Bland or already has an API key. |
| `bland mcp` ([CLI](https://docs.bland.ai/sdks/cli.md)) | A local stdio server bundled with the Bland CLI. | You prefer a local process, or your agent has no API key yet and needs to [onboard itself](https://docs.bland.ai/platform/connect-your-agent.md). |
| `https://docs.bland.ai/mcp` | The docs site's own MCP (search-only, no auth). | You only want documentation search. |

## Security notes

* Treat your API key like a password. Use environment variables or your client's secret storage. Never commit it to a repo.
* A sign-in connection acts as you, in the organization you chose, with the permissions of your role there. Review the consent screen before you approve, and disconnect apps you no longer use.
* OAuth tokens are only valid on `/v1/mcp`. They don't work on the REST API.
* Tools that spend money or touch live traffic (placing calls, publishing agents) are marked destructive so your client asks before running them. Review what your agent proposes before approving.
* MCP tool results can contain untrusted content (e.g. call transcripts of real conversations). Prompt-injection-aware clients like Claude Code treat tool output as data, but keep it in mind when building your own agent loops.

## Next steps

> [card] [MCP clients](https://docs.bland.ai/integrations/mcp/clients.md)
>
> Connect the server directly to VS Code, Windsurf, Gemini CLI, or any client, without the plugin.

> [card] [Agent Phone Plan](https://docs.bland.ai/platform/agent-phone-plan.md)
>
> A dedicated number with unlimited US and Canada calling and texting, built for one agent.

> [card] [Tool reference](https://docs.bland.ai/integrations/mcp/tools.md)
>
> Every tool the server exposes, grouped by what it does.

> [card] [Send your first call](https://docs.bland.ai/quickstart)
>
> The 5-minute API quickstart.

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.