Studio MCP¶

The DialoX Studio MCP server lets an AI assistant in your editor work with the bots you already develop in Studio. The assistant can list your bots, read, create, edit, and delete draft scripts, run tests, check parse errors, chat with the draft bot in a studio conversation, inspect those conversations, and look up this developer documentation — without you copying scripts in and out by hand.

MCP (Model Context Protocol) is an open standard. Any editor or agent that can connect to a remote MCP server can use it. You sign in with your Studio account. The assistant only sees bots and conversations you can already access, and it cannot do more than your Studio role allows.

What the assistant can do¶

Typical bot-development work looks like this:

Find a bot (list_bots), then list its draft scripts (list_scripts).
Read a script (read_script) and propose a change, or create a new draft file (create_script).
Write the updated draft body back (write_script), change a file's name or type (update_script), or remove a draft file (delete_script). Those mutations return parse diagnostics for the whole draft (publishable plus errors and warnings).
Call get_bot_diagnostics when you need a parse check without writing. Read or replace the Tests section (read_bot_tests, write_bot_tests) and run bot tests (run_bot_tests).
Chat with the draft (create_studio_conversation returns the bot's opening turn; each chat is one user turn) and inspect the transcript (list_studio_conversations, get_conversation).
Review the draft in Studio and publish from there when you are ready.

The assistant can also search and open these docs (search_docs, get_docs), export or import a bot zip, chat with the draft bot in a studio conversation, and read those conversations afterwards.

Writes and deletes update the draft in Studio, the same as editing or removing a file in the Studio code editor. Publishing is not available through MCP — do that in Studio. The main BubbleScript file cannot be deleted through MCP.

Full-file writes

write_script and write_bot_tests replace the entire script or test suite. Ask the assistant to read the current draft first, then apply a focused change. After a write, open the file in Studio and review the diff before you publish.

Permissions¶

The consent page only lists scopes your Studio role can use. You can uncheck any of them before you approve.

Scope	What the assistant may attempt
`bot:read`	List organisations and bots, read draft scripts, and read parse diagnostics
`bot:write`	Create bots and create, edit, or delete draft scripts and import or export bot zips
`bot:build`	Read, write, and run draft bot tests, and chat with the draft bot in a studio conversation
`conversation:read`	List studio conversations, read conversation history, and request customer-data access

Scopes are not hierarchical: granting bot:write does not include bot:read.

A Developer typically sees all four. A role that can only view bots will only be offered bot:read. Organisation Administrator is not a platform-wide Super user — Studio still checks access per bot.

ping, search_docs, and get_docs are available with any valid login. The editor only lists the other tools for scopes you granted and still have in Studio.

To grant extra scopes later, disconnect the MCP server in your editor and connect again so the consent screen is shown.

Tools¶

Studio chat is a turn-based API: create_studio_conversation returns the bot's opening turn; each chat call is one user turn and waits for the bot's reply.

Tool	Scope	What it does
`ping`	any	Health check. Returns `pong from you@example.com`.
`search_docs`	any	Search this developer documentation. Pass a `query`; optional `limit` (default 8).
`get_docs`	any	Return a docs page as markdown. Pass a `path` from `search_docs` (for example `bubblescript/statements`) and optional `section` (a heading or function name). Large pages return a heading list — call again with `section`. Also accepts a `https://developer.dialox.ai/...` URL.
`create_bot`	`bot:write`	Create a new bot without a license on a customer or environment organisation you can create bots in. Requires `organisation_id` and `title`. Optional `locale` and `extra_locales` (ISO 639-1, e.g. `en`), `region` (alpha-2, e.g. `NL`), and `timezone` (IANA, e.g. `Europe/Amsterdam`). Returns `{id, title, organisation_id, locale, extra_locales, region, timezone}`.
`list_bots`	`bot:read`	Bots you can access, across organisations. Optional `search`, `from` (default 0), and `size` (default 50, max 100). Returns `from`, `size`, `has_more`, and `rows` (`id`, `title`, `organisation_id`).
`list_organisations`	`bot:read`	Organisations you can access. Optional `search`, `from` (default 0), and `size` (default 50, max 100). Returns `from`, `size`, `has_more`, and `rows` (`id`, `title`, `type`, `parent_id`).
`list_scripts`	`bot:read`	Draft scripts for one `bot_id`. Returns `id`, `title`, and `type`.
`read_script`	`bot:read`	One draft script, by `script_id` or by `bot_id` + `title`.
`create_script`	`bot:write`	Create a new draft script. Requires `bot_id`, `title`, and `type` (for example `text/bubblescript` or `text/yaml+data`). Optional `body`; omit it to use the type default. Returns script metadata plus `publishable` and `diagnostics`.
`delete_script`	`bot:write`	Delete a draft script by `script_id`, or by `bot_id` + `title`. Cannot delete the main BubbleScript file. Returns the deleted file metadata plus remaining-draft `publishable` and `diagnostics`.
`write_script`	`bot:write`	Replace a draft script body. Same identity arguments as `read_script`, plus `body`. Returns script metadata plus `publishable` and `diagnostics`.
`update_script`	`bot:write`	Change a draft script title and/or type (not the body). Same identity as `read_script`, plus `new_title` and/or `type`. Cannot rename `main` or `bot`. Returns script metadata plus `publishable` and `diagnostics`.
`get_bot_diagnostics`	`bot:read`	Fresh parse status for a bot without writing: `publishable` plus per-file errors and warnings.
`read_bot_tests`	`bot:build`	Read the draft Tests section (`.bot_tests` JSON). An empty suite is `{tests: []}`.
`write_bot_tests`	`bot:build`	Replace the draft test suite with JSON `{tests: [...]}`. This replaces the whole suite — call `read_bot_tests` first to merge. Regenerates `generated/tests/auto`.
`run_bot_tests`	`bot:build`	Run draft tests for a `bot_id`. Optional `script` or `test_case` to run a subset. Large suites can be slow.
`create_studio_conversation`	`bot:build`	Turn-based studio chat: start a studio-channel conversation with the draft bot and return the bot's opening turn (bots always talk first). Pass `bot_id` and optional `group`. Omitting `group` creates a new UUID so the Studio simulator's `main` conversation is left alone. User key is `studio:<your user id>`. Returns `{id, bot_id, group, actions, is_final, locale, ssml, logs}` — `id` is the conversation database UUID.
`chat`	`bot:build`	The next user turn on that conversation. Pass `conversation_id` (the database UUID) and either `message` or `action` (JSON user action). Waits for the bot's reply and returns `{actions, is_final, locale, ssml, logs}`. `logs` is this turn's debug IO (`log` and other session output) as `{subject, message}` rows.
`download_bot_zip`	`bot:write`	Mint a short-lived download URL. Returns `{url, token, authorization, filename, expires_in}`. HTTP GET `url` with `Authorization: Bearer <token>` within `expires_in` seconds to fetch the zip. Optional extras: `include_kv`, `include_tokens`, `include_calendar`, `include_knowledge`.
`upload_bot_zip`	`bot:write`	Mint a short-lived upload URL for an existing `bot_id`. Returns `{url, token, authorization, method, expires_in, max_bytes}`. HTTP POST the zip to `url` with `Authorization: Bearer <token>` as a raw `application/zip` body. Limit is 20 MB (`max_bytes`).
`list_studio_conversations`	`conversation:read`	Studio-channel conversations for a `bot_id` (the in-Studio simulator). Optional `search`, `from` (default 0), and `size` (default 50, max 100). Returns `from`, `size`, `has_more`, and `rows`.
`get_conversation`	`conversation:read`	One conversation: metadata, tags, actions, and logs. Studio conversations are available to developers; other channels need an inbox role. Derived (agency) roles also need an accepted customer-data access request for non-studio channels — call `request_customer_data_access` first.
`request_customer_data_access`	`conversation:read`	Request organisation-level access to real (non-studio) customer data. Pass `organisation_id` and either `access_reason` (short reason, at least two words) or `support_case` when the org requires support-case requests. Ask the user for the value; do not invent it. Logged like Studio access requests.

Script identity¶

For read_script, write_script, update_script, and delete_script, pass either script_id or both bot_id and title. The MCP JSON Schema lists all three identity fields as optional, but the server rejects calls that do not match that rule (same as the Studio API).

Response formats¶

Compact JSON shapes returned by common tools:

{"from":0,"size":50,"has_more":false,"rows":[{"id":"…","title":"My bot","organisation_id":"…"}]}

{"id":"…","bot_id":"…","title":"main","type":"text/bubblescript","body":"dialog main do\nend"}

{"id":"…","bot_id":"…","title":"main","type":"text/bubblescript","publishable":false,"diagnostics":[{"severity":"error","message":"…","file":"main","line":1,"column":1,"dialog":null}]}

{"publishable":true,"diagnostics":[{"severity":"warning","message":"Prompt 'x': temperature is not supported…","file":"prompts","line":null,"column":null,"dialog":null}]}

{"url":"https://studio.example/mcp/api/bots/…/download","token":"…","authorization":"Bearer","filename":"my-bot.zip","expires_in":300}

Zip download and upload use short-lived tokens: call the tool, then HTTP GET or POST the returned url with Authorization: Bearer <token> before expires_in elapses. Do not put the zip bytes in the MCP tool call.

{"url":"https://studio.example/mcp/api/bots/…/upload","token":"…","authorization":"Bearer","method":"POST","expires_in":300,"max_bytes":20971520}

{"tests":[{"test_case":"Greeting","success":true,"messages":[]}]}

{"id":"…","bot_id":"…","group":"…","actions":[{"type":"text","payload":{"message":"Hello"}}],"is_final":false,"locale":"en","ssml":"<speak>…</speak>","logs":[{"subject":"main","message":"hello"}]}

{"actions":[{"type":"text","payload":{"message":"Hello"}}],"is_final":false,"locale":"en","ssml":"<speak>…</speak>","logs":[{"subject":"main","message":"hello"}]}

Diagnostics semantics¶

create_script, write_script, update_script, and delete_script return the same publishable and diagnostics fields on the mutation result. get_bot_diagnostics runs that parse without writing (not the full Language Server check used for auxiliary scripts such as group or operator_join). Both return errors and warnings. publishable is false only when at least one diagnostic has severity error; warnings alone still allow publish in Studio.

Examples: invalid BubbleScript syntax → error; a prompts entry with temperature on a model that ignores it → warning.

Audit log¶

Everything the assistant changes is logged against your Studio account with the note via MCP, so you can tell editor-driven changes from work done in Studio. Script creates, edits, renames, and deletes, test-suite writes, and zip imports appear in the bot's audit log, in the organisation audit log, and in your user audit log. Reading and exporting are not logged; viewing a customer conversation stays logged the same way it is in the inbox.

REST API endpoint details are not in these HTML-shell doc pages. Point the assistant at the OpenAPI specs: v2 and v1.

Set up in any MCP-capable editor¶

The DialoX server is a remote HTTP MCP server with OAuth. You do not run a command or store a token in the config file.

In the editor's MCP settings, add a remote HTTP server.
Set the URL to https://studio.dialox.ai/mcp. If you previously used https://mcp.dialox.ai/mcp, update the URL and reconnect so the editor obtains a new token for the Studio resource.
Do not add an Authorization header or API key. The editor discovers login from the server and opens your browser.
Log in to Studio if asked, then approve the permissions you want the assistant to have.
Confirm the server is connected and that tools such as ping and list_bots appear.
In a chat or agent session, ask the assistant to use those tools. Most editors ask you to approve each call the first time.

The exact menu names differ (Cursor, VS Code, Claude Desktop, Windsurf, Zed, and others), but the URL and the browser login are the same. Prefer the editor's built-in remote MCP + OAuth support over a local proxy.

Set up in Cursor¶

Cursor 1.0 and later can register itself with DialoX, open the Studio login page, and store the access token. You only add the server URL.

Official Cursor MCP reference: cursor.com/docs/mcp.

1. Add the server¶

You can add the server from the UI or by editing mcp.json. Both end up in the same place.

From the UI

Open Cursor Settings → Tools & MCP (also under Customize → Tools & MCP in the sidebar).
Add a new MCP server.
Choose a remote / HTTP server and set the URL to https://studio.dialox.ai/mcp.
Give it a clear name, for example dialox-studio.

From mcp.json

This project only — create or edit .cursor/mcp.json in the project root.
Every workspace — create or edit ~/.cursor/mcp.json in your home directory.

{
  "mcpServers": {
    "dialox-studio": {
      "url": "https://studio.dialox.ai/mcp"
    }
  }
}

Do not add headers or auth for the hosted DialoX server. Cursor obtains a bearer token through OAuth.

Reload MCP after you save the file: restart Cursor, or toggle the server off and on under Tools & MCP.

Enabling the server starts OAuth. There is often no separate Connect button — turning dialox-studio on opens your default browser.

Open Cursor Settings → Tools & MCP.
Enable dialox-studio. If it shows "Needs authentication", click that label or the Connect control.
Log in to Studio (https://studio.dialox.ai) if the browser asks.
On the consent page, leave the permissions you want checked and uncheck the rest. Approve.
The browser redirects back to Cursor (http://localhost:8787/callback on recent desktop builds, or the cursor:// handler on some installs). Cursor finishes the token exchange.

You should now see the server as connected, without "Needs authentication".

Cursor Cloud Agents and the Cursor web app use a different redirect (https://www.cursor.com/agents/mcp/oauth/callback). DialoX accepts that during login; you still add the same https://studio.dialox.ai/mcp URL.

3. Check that tools are available¶

In Tools & MCP, open Available Tools for dialox-studio. A full Developer grant includes ping, search_docs, get_docs, list_bots, list_scripts, read_script, create_script, delete_script, write_script, update_script, get_bot_diagnostics, read_bot_tests, write_bot_tests, run_bot_tests, download_bot_zip, upload_bot_zip, create_studio_conversation, chat, list_studio_conversations, get_conversation, and request_customer_data_access.
Open a chat in Agent mode.
Ask Cursor to call the tools, for example:

Use the dialox-studio ping tool, then list_bots, and show me the results.

Approve the tool calls if Cursor asks. ping returns pong from your@email.com. list_bots returns a paginated JSON object with rows (id, title, organisation_id) for bots you can open in Studio.

Cursor asks for approval before MCP tools run, unless you have changed the run mode. Expand a tool call to see the arguments.

Example prompts¶

Once the server is connected, you can stay in chat and refer to bots by title. Useful starting points:

List my bots and open the draft main script of "Support bot".
Explain what this dialog does, then add a fallback when the user says they want a human.
Search the DialoX docs for ask and show me the statement reference.
Run the tests for this bot and summarise any failures.
Start a studio conversation with this bot, show me its opening turn, then reply and show what it said next.
Check parse diagnostics for bot <bot_id> and fix the errors in the draft.

Name the MCP server or the tool when Cursor might pick the wrong integration: Use dialox-studio read_script…

Troubleshooting¶

Symptom	What to try
Server stays on "Needs authentication"	Enable the server again so the browser login can start. Complete login and Approve on the consent page.
Browser opens but login fails	Confirm you can sign in to studio.dialox.ai in the same browser.
Tools list is short	You unchecked scopes, or your Studio role cannot use them. Disconnect and reconnect to re-consent. A missing `write_script`, `create_script`, `update_script`, or `delete_script` means `bot:write` was not granted or you cannot edit scripts in Studio.
Tool returns "Missing required scope"	Re-consent and include that scope.
Tool returns a permission error	You can see the bot in the list but your role cannot edit, test, or read that conversation. Check roles in Studio.
`write_script`, `create_script`, `update_script`, or `delete_script` says the operation is not allowed on an app	Installed app / skill files are not editable this way. Edit the bot's own scripts instead.
OAuth error or HTML instead of a token	Open Output → MCP Logs (View → Output, then the MCP Logs channel). Connection problems show up there.

If you previously granted only a subset of scopes, disable the server and enable it again so Cursor can show the consent page with the extra scopes. Before enabling again, you might need execute the Cursor: Clear All MCP Tokens command.