How-to guide

Connect VoiceLayer to ChatGPT, Claude, Cursor

Add VoiceLayer's remote MCP server to ChatGPT, Claude or Cursor with OAuth, choose what the app may do, and revoke it from the Access page.

What you'll build

An AI app (ChatGPT, Claude or Cursor) that uses your VoiceLayer workspace: it sends and reads messages, places calls, or runs a mailbox, within the permissions you choose. You sign in once in your browser; no API key is pasted anywhere, and you can end the connection at any time.

Prerequisites

  • A VoiceLayer account where you are an Admin of the workspace. Only an Admin can allow an app.
  • The app: ChatGPT with developer mode on, Claude with custom connectors, or Cursor.

The server address is the same for all three:

https://api.vlayers.ai/v1/mcp

How it works

You give the app the address. The first time it uses VoiceLayer, VoiceLayer answers that it needs you to sign in and tells the app where to ask. The app opens your browser at a VoiceLayer page that names the app, shows the workspace and offers a preset. When you allow it, the app gets a short-lived token (about ten minutes) and a refresh token. Every call the app makes is checked against what you allowed, and against your choice to revoke it, at that moment.

Step 1: Add the server

Open Access, choose New, then Connect an app, then the Cursor tab. Choose Add to Cursor to open Cursor with the server filled in, or copy this block into Cursor's mcp.json:

{
  "mcpServers": {
    "voicelayer": { "url": "https://api.vlayers.ai/v1/mcp" }
  }
}

Note there is no headers entry. The first time Cursor uses a VoiceLayer tool, it opens your browser.

Step 2: Choose what the app may do

The page offers five presets and Choose…. It selects the smallest preset that covers what the app asked for. ChatGPT and Claude ask for everything, so you see Build and run agents selected. You can pick any other preset instead. Everything is never selected for you, and only an Admin can choose it.

PresetThe app canIt cannot
Messages and inboxSend and read messages on every channel, decide who answers a conversation, set up and use mailboxes, read eventsPlace calls, change agents, touch memory
CallsPlace calls, follow them and steer them, see your numbersSend messages
Build and run agentsBuild and change agents, playbooks, flows, tools and channels, run campaigns (which place calls), follow calls, use memory, send messages, read what hosted agents print. Ask it "What's left to set up?"Manage people, keys or spending, loosen your own limits
Look, don't touchSee your agents, settings, conversations, calls, memory, spending, request logs and what hosted agents printChange anything
Everything (Admin only)Everything you can do in the dashboard, including people, keys and billingEnter or change a payment card, or buy a phone number (both stay in the dashboard)

Choose… opens switches grouped by area (messages, calls, agents, memory, money, people and keys), each saying what it lets the app do. The switches for people, keys, spending, memory spaces and loosening your limits are for Admins only; a Member sees them greyed out with the reason.

To change what a connected app can do later, connect VoiceLayer again from the app and choose again: it gets a new connection, and you cut the old one off on the Access page.

The page also shows the redirect address the app will return to. If it is not an address you expect, choose Cancel.

Step 3: Use it

Ask the app to do something the preset allows:

  • "List the channels my VoiceLayer workspace has."
  • "Text +15550123 that their order is ready." (Messaging)
  • "Call the number on this contract and ask for a delivery slot." (Calls)

The app sees only the tools its preset allows. A tool outside the preset is not listed, and a call to it is refused with 403 insufficient_scope.

Step 4: See and end the connection

Open Access in the dashboard. The app is listed under connected apps, with what it may do, when it last used VoiceLayer, and anything it was refused this week. From the same row:

  • Limit to… narrows the app to one Line or one mailbox. This only narrows; to widen, connect again.
  • Revoke ends it. The app's next call is refused with token_revoked and its refresh token no longer works. Calls already in progress finish. See Access and keys.

Using an API key instead

A host that takes a header and no OAuth (the OpenAI Responses API, a script, Claude Code with --header) can use an API key from Access, New, Create API key. See Authentication and API keys and Connect an AI agent (MCP).

Test it

With the app connected, ask it to list your channels. Then revoke the connection on the Access page and ask again: the app should tell you it needs to sign in again.

Common errors

ErrorStatusHow to fix
unauthorized401Send Authorization: Bearer <key> with a secret key from the dashboard (Access → New → Create API key). Test keys start with vl_test_.
insufficient_scope403Use a key with the scope named in details.required, or one whose restriction covers this channel or Binding.

If the app says it could not reach the server before it ever opens a browser, check that the address is exactly https://api.vlayers.ai/v1/mcp, with no trailing slash.

Next steps

On this page