# Connect an AI agent (MCP)

> Give Claude, ChatGPT or any MCP host your channels with one remote MCP server and an API key.

Source: https://docs.vlayers.ai/developers/mcp

Kind: How-to guide

## What you'll build

An AI agent that can list your channels, send and reply to messages, read conversations and hand them to a person, through VoiceLayer's remote [Model Context Protocol](https://modelcontextprotocol.io) server.

## Prerequisites

- An API key. A test key is the safe start: the agent's sends then go to a simulated carrier. In the dashboard, **Developers → API keys → Create key**; for an MCP host pick "Cursor, Claude Code, or another MCP client". See [Authentication and API keys](https://docs.vlayers.ai/get-started/authentication).
- An MCP host that can call a remote server over Streamable HTTP and send an `Authorization` header: Claude Code, Claude Desktop, the OpenAI Responses API, or one of the [framework packages](https://docs.vlayers.ai/developers/frameworks/claude).

## The server

- **Endpoint:** `https://api.vlayers.ai/v1/mcp` (Streamable HTTP)
- **Auth:** `Authorization: Bearer <API key>`

The key decides what the agent may do. Its scopes gate each tool, and a key limited to some channels (for example `telegram`) sees and sends on those only. Each tool calls the API route it maps to with that key, so every check the API makes applies here too.

| Tool | Calls | Scope | Kind |
|---|---|---|---|
| `channels_list` | `GET /v1/channels` | `channels:read` | read |
| `message_send` | `POST /v1/messages` | `messages:send` | write |
| `message_reply` | `POST /v1/conversations/{id}/messages` | `messages:send` | write |
| `conversations_list` | `GET /v1/conversations` | `messages:read` | read |
| `conversation_read` | `GET /v1/conversations/{id}/messages` | `messages:read` | read |
| `conversation_set_controller` | `PATCH /v1/conversations/{id}` | `conversations:control` | write |
| `messages_wait` | `GET /v1/events` | `events:read` | read |
| `whatsapp_templates_list` | `GET /v1/channels/whatsapp/templates` | `channels:read` | read |

`message_send` and `message_reply` take an optional `idempotencyKey`. Pass one when the agent may retry; without it, an MCP send can go out twice.

## Step 1: Add the server to Claude Code

```bash
claude mcp add --transport http voicelayer https://api.vlayers.ai/v1/mcp \
  --header "Authorization: Bearer $VOICELAYER_API_KEY"
```

## Step 2: Or add it to a host that takes a JSON config

Claude Desktop and other hosts read a config file. Put your key in place of `vl_...`:

```json
{
  "mcpServers": {
    "voicelayer": {
      "type": "http",
      "url": "https://api.vlayers.ai/v1/mcp",
      "headers": { "Authorization": "Bearer vl_..." }
    }
  }
}
```

## Step 3: Or call it from the OpenAI Responses API

The Responses API calls remote MCP servers as a tool:

```json
{
  "model": "gpt-5",
  "input": "Text +15550123 that their order is ready.",
  "tools": [{
    "type": "mcp",
    "server_label": "voicelayer",
    "server_url": "https://api.vlayers.ai/v1/mcp",
    "headers": { "Authorization": "Bearer vl_..." },
    "require_approval": "never"
  }]
}
```

## Connectors in the Claude and ChatGPT apps

The custom connectors in the Claude and ChatGPT apps sign in with OAuth, not a header. OAuth for the VoiceLayer server is not available yet; until it is, use a host that lets you set the `Authorization` header (above).

## Test it

With a test key, ask your agent: "Text +15550123 that their order is ready." The send goes to a simulated carrier at no cost. To give it something to answer, simulate a message with `POST /v1/test/inbound` (see [Test mode](https://docs.vlayers.ai/developers/test-mode)) and ask it to read and reply to its conversations.

## Common errors

| Error | Status | How to fix |
|---|---|---|
| [`unauthorized`](https://docs.vlayers.ai/errors/unauthorized) | 401 | Send `Authorization: Bearer <key>` with a secret key from the dashboard (Developers → API keys). Test keys start with `vl_test_`. |
| [`insufficient_scope`](https://docs.vlayers.ai/errors/insufficient_scope) | 403 | Use a key with the scope named in `details.required`, or one whose restriction covers this channel or Binding. |
| [`no_sender`](https://docs.vlayers.ai/errors/no_sender) | 409 | Connect a sender for the channel in the dashboard (for email, create a mailbox), or name one in `from`. |
| [`test_address_required`](https://docs.vlayers.ai/errors/test_address_required) | 422 | Use a reserved test address, or a live key to reach a real person. |
| [`window_closed`](https://docs.vlayers.ai/errors/window_closed) | 409 | Wait for the person to write again. Template sends, the way to reach someone outside the window, are not available yet (`operation_not_supported`). |

## Next steps

- [Framework packages](https://docs.vlayers.ai/developers/frameworks/claude): the same tools in the Claude Agent SDK, OpenAI Agents, the Vercel AI SDK and LangChain.
- [Conversations and handoff](https://docs.vlayers.ai/developers/handoff).
- [Test mode](https://docs.vlayers.ai/developers/test-mode).