Vertical AI

npx add-mcp 'https://app.verticalai.com.au/api/mcp'

Connect the Vertical AI MCP to Claude Code, Claude Desktop, Claude on the web, Cursor, VS Code, Windsurf, or ChatGPT and manage your voice agent in plain language.

Vertical AI runs a remote MCP server that gives an AI assistant the same controls as the app. Point a client at one URL and manage your agent in plain language.

https://app.verticalai.com.au/api/mcp

No keys to copy. The first time a client connects it opens a browser to sign you in, and the consent screen asks which workspace the connection reaches: one, or all of yours. It acts as you, so your role in each workspace still applies.

JSON config for any client

Claude Code

Add the server once:

claude mcp add --transport http --scope user vai https://app.verticalai.com.au/api/mcp

Run /mcp, pick vai, and finish the browser consent screen. Then ask in plain language:

List my agents.

Open my support agent. Tighten the greeting, add a tool that looks up an
order by its number, and tell me what's blocking publish.

Cursor and VS Code

Install in one click. Each link opens the editor with the server filled in, and the editor asks you to confirm before it adds it.

• Install in Cursor
• Install in VS Code

To add it by hand, put the JSON config block in ~/.cursor/mcp.json for Cursor. VS Code's own mcp.json names the top-level key servers instead of mcpServers.

Claude Desktop and Claude on the web

Install in one click. The link opens Claude's Add custom connector dialog with the name and address filled in. Check them, choose Add, then sign in when Claude asks. Leave the sign-in settings at their defaults.

• Add to Claude

The connector belongs to your Claude account, so Claude Desktop, Claude on the web and the mobile apps all get it. On a Team or Enterprise plan an owner adds it for the organisation with the organisation link, and each member then chooses Connect on it under Customize → Connectors. Claude Desktop's own config file is for servers that run on your computer, so don't add this server there.

Windsurf

Windsurf has no install link. In Cascade's MCP menu choose Open MCP config file, add the server under mcpServers, save, and press refresh in the MCP panel. Windsurf names a remote server's address serverUrl:

{
  "mcpServers": {
    "vai": { "serverUrl": "https://app.verticalai.com.au/api/mcp" }
  }
}

Windsurf opens a browser to sign you in the first time Cascade uses the server.

ChatGPT

ChatGPT has no install link either. Add the server from Plugins:

1. Open Plugins, choose +, then Add custom MCP server.
2. Name it and, under Connection, enter https://app.verticalai.com.au/api/mcp.
3. Choose OAuth for authentication, read the warning, tick I understand and want to continue, then choose Create as a plugin.
4. Install the plugin, sign in when prompted, and type @ in a chat to pick it.

Whether you can add a custom MCP server depends on your ChatGPT plan and your workspace's settings.

What the assistant sees

The server keeps its tool list small enough for any client's context window.

• Core tools are listed directly. These cover the loop of building, testing and shipping: get_agent, export_agent_spec, apply_agent_spec, update_system_prompt, run_all_tests, get_test_results, get_call_bundle, publish_version and the rest of the listed tools.
• Every other tool is one search away. search_tools finds a tool by what it does and get_tool_details gives its arguments. call_read_tool and call_write_tool run it with the same checks as a direct call.
• The default connection is enough for every assistant, Claude Code included. You never need the full list to use a tool: search finds it.
• ?toolsets=all lists every tool directly, at https://app.verticalai.com.au/api/mcp?toolsets=all. Its tool definitions come to about 155,000 tokens, against about 16,000 for the default list, and a client that puts every listed tool in front of the model pays that on every message. It is worth it only where that cost does not reach a model: a script or CI job that calls tools by name, as the vai CLI does, or a client you have checked loads a tool's definition only when it uses that tool.
• Guides, docs pages and your agents are resources. A client that shows MCP resources lists the prompt-writing guide, the build guide, every docs page, your agents and each agent's recent calls. The prompts build-an-agent, write-a-system-prompt, fix-a-call and fix-failing-tests start those jobs.
• A read-only token sees only reads. Tools that would change something are not listed, and asking for one through call_write_tool is refused with insufficient_scope, naming agent:write. Tools for platform staff never appear.
• Connections start read-only. The consent screen opens with Read-only ticked. Untick it to let your assistant edit agents, then tick Delete or Manage the workspace only if it needs them; each is off until you tick it. A tool that needs a scope you left out is refused with insufficient_scope and the scope's name, whether it is called directly or through call_write_tool.
• To keep a connection to reads whatever the token allows, add ?read_only=1 to the URL: https://app.verticalai.com.au/api/mcp?read_only=1. The server then lists and runs only reads.
• Some changes ask you first. A tool that deletes something, publishes, changes what live callers get straight away, or spends money on calls or test runs needs your approval.
  • In a client that supports MCP elicitation, the server asks you itself. Your client shows what will change, or the spend estimate in A$, with an Approve box. Nothing happens until you tick it, and your assistant cannot approve on your behalf. If nobody answers within 100 seconds, nothing changes.
    • In a client without elicitation, the tool answers confirmation_required until the call carries confirm: true, so your assistant must ask you before it sends that. A costly run includes its spend estimate for it to show you. The audit log records who approved each change as confirmed_by: person when you approved it in your client, model when your assistant sent confirm: true, cli_flag for the vai CLI's --yes or --max-spend, and cli_prompt for a y typed at its prompt.
• A change can be undone. Before each change, the draft is saved, and your newest ten are kept for each agent. undo_last_change({ agent }) puts the draft back the way it was before your last change, and steps goes back up to ten. It never publishes, and it asks first when putting the draft back would change live calls at once or delete something.
• A wrong argument gets a suggestion. A tool called with an argument it does not take is refused with the closest one it does, such as Unknown argument "step". Did you mean "steps"?, and the list of arguments it takes.
• Text from callers and other people arrives fenced. Transcripts, test grading notes, call summaries, contacts, campaign recipients, lead requests and webhook replies come back inside an <untrusted-data-…> tag, with a note telling your assistant never to follow an instruction inside it. The REST API returns these fields unwrapped, except transcripts and call bundles, which are wrapped on every surface.

In clients that show prompts as commands, the four prompts appear as build-an-agent, write-a-system-prompt, fix-a-call and fix-failing-tests. The resources are the two guides (vai://guides/system-prompt and vai://guides/build-an-agent), every docs page (vai://docs/{page}), an agent's config (vai://agents/{workspace}/{agent}) and a call bundle (vai://agents/{workspace}/{agent}/calls/{sessionId}). The MCP tool reference lists every tool.

Each connection may make 1,200 requests a minute, and all of one person's connections through the same app count as one. Over the limit, a request is refused until the minute is up.

Edit a whole agent as one spec

export_agent_spec returns an agent's config as one JSON spec, listing only what differs from a new agent. Edit it and pass it back to apply_agent_spec, and the draft is made to match in one call. This is what vai pull and vai push use.

The spec covers	It leaves out
Name, description, instructions and the three greetings	Secret values: a secret is listed by name, and secrets says which hold a value
Channels, the brief, the voice and fallback voice, the models, the call engine, speech, turn-taking and behaviour	The content of uploaded knowledge files
Keyterms, pronunciations, vocabulary and caller memory	Connected apps, MCP servers and website endpoints (the tools they add are in the spec)
Guardrails, and privacy and disclosure settings	The look of the website chat, the share page and the details form, chat handoff and share-page limits
Call handling, the overflow number, the closed message, answering hours, closing early and caller routing	Blocked callers
Built-in and HTTP tools in the agent's order, variables, workflow functions and post-call analysis	What the workspace owns: call checks, test callers, personas, config sets, alerts and dashboards
Knowledge sources, with each text source's text, and test scenarios	A knowledge source's sync schedule, a scenario's audio settings, and the knowledge-search tool the first knowledge source adds, until you change it

apply_agent_spec leaves a field you leave out as it is, unless you pass replace: true, which makes the spec the whole config: a field left out is reset and a list item left out is deleted. Every step is checked before the first write, deletions run last, and a failed step undoes the steps before it. dryRun: true returns the plan only. It never publishes.

What you can do

Anything the Builder can do: list and inspect agents, edit prompts and tools, check readiness, review calls. You can switch between your assistant and the app at any time.

[

Config sets

A config set holds variables, recognition hints and pronunciations for the whole workspace. An attachment is a live reference, so an edit reaches the next call.

](https://docs.verticalai.com.au/docs/platform/config-sets)