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/mcpHow 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.
| Preset | The app can | It cannot |
|---|---|---|
| Messages and inbox | Send and read messages on every channel, decide who answers a conversation, set up and use mailboxes, read events | Place calls, change agents, touch memory |
| Calls | Place calls, follow them and steer them, see your numbers | Send messages |
| Build and run agents | Build 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 touch | See your agents, settings, conversations, calls, memory, spending, request logs and what hosted agents print | Change anything |
| Everything (Admin only) | Everything you can do in the dashboard, including people, keys and billing | Enter 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_revokedand 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
| Error | Status | How to fix |
|---|---|---|
unauthorized | 401 | Send Authorization: Bearer <key> with a secret key from the dashboard (Access → New → Create API key). 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. |
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
- Access and keys: every way into your workspace, in one list.
- Give an outside agent an inbox: let the app run its own email address.