Connect an AI agent (MCP)
Give Claude, ChatGPT or any MCP host your channels with one remote MCP server and an API key.
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 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.
- An MCP host that can call a remote server over Streamable HTTP and send an
Authorizationheader: Claude Code, Claude Desktop, the OpenAI Responses API, or one of the framework packages.
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
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_...:
{
"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:
{
"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) and ask it to read and reply to its conversations.
Common errors
| Error | Status | How to fix |
|---|---|---|
unauthorized | 401 | Send Authorization: Bearer <key> with a secret key from the dashboard (Developers → API keys). Test keys start with vl_test_. |
insufficient_scope | 403 | Use a key with the scope named in details.required, or one whose restriction covers this channel or Binding. |
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 | 422 | Use a reserved test address, or a live key to reach a real person. |
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: the same tools in the Claude Agent SDK, OpenAI Agents, the Vercel AI SDK and LangChain.
- Conversations and handoff.
- Test mode.