cdbx MCP Server

The cdbx MCP server lets external AI clients read from and build in cdbx directly — this is what makes cdbx callable infrastructure for any agent, not just a standalone app you use through a browser.

In a team? If you build in a team, anything an AI client creates for you here belongs to your team and starts private to you, the same as if you had made it in cdbx. See Team Workspaces.

Works with Claude Code, Cursor, Claude Desktop, claude.ai (web), ChatGPT's custom connectors, Grok's custom connectors, and any other MCP client that speaks standard OAuth — cdbx runs a generic OAuth 2.1 authorization server, not something built only for Claude.

Once connected, another AI can list your apps, read source files, fetch preview HTML — and, with the write scope, create new apps and push code into them, so you can build in cdbx without opening a browser.

Setup

1. Generate an API key

Go to API → API Keys in the sidebar, enter a label (e.g. "Claude Desktop"), select MCP Server to read, and additionally MCP Server (write) if you want the AI to create or edit things (not just read them), then click Generate key. Copy the key — it's shown once.

2. Add to your MCP client

Setup differs by client — Claude Desktop's config file only understands a local server (something it can launch as a command), while Claude Code and Cursor can connect straight to a remote URL. Use the section that matches your client.

Claude Code (and Cursor)

These clients can talk to cdbx's remote MCP server directly — no local process needed.

For Claude Code, run:

claude mcp add --transport http cdbx https://cdbx.ai/api/mcp/server \
  --header "Authorization: Bearer cdbx_your_key_here"

For Cursor, add this to ~/.cursor/mcp.json (or your project's .cursor/mcp.json):

{
  "mcpServers": {
    "cdbx": {
      "url": "https://cdbx.ai/api/mcp/server",
      "headers": {
        "Authorization": "Bearer cdbx_your_key_here"
      }
    }
  }
}

Claude Desktop

Claude Desktop's config file (claude_desktop_config.json) only accepts local stdio servers (command/args) — it does not accept a remote url entry. So instead of pointing at cdbx's server directly, you run a small local bridge, @cdbx.ai/mcp (opens in a new tab), that relays stdio to the same remote endpoint Claude Code and Cursor use.

Open Settings → Developer → Edit Config in Claude Desktop — this opens claude_desktop_config.json directly (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json) in your default editor. Add:

{
  "mcpServers": {
    "cdbx": {
      "command": "npx",
      "args": ["-y", "@cdbx.ai/mcp"],
      "env": { "CDBX_API_KEY": "cdbx_your_key_here" }
    }
  }
}

Restart Claude Desktop. The cdbx tools will appear in the tool picker.

(Claude Desktop also has a Settings → Connectors → Add custom connector UI that only accepts a URL, no Bearer token field. Since cdbx now runs a standard OAuth server, you can use that UI instead of the config file above — same as the claude.ai instructions below, just inside Desktop.)

claude.ai (web)

claude.ai's Settings → Connectors → Add custom connector dialog only accepts a URL — no field for pasting an API key. That's fine now: cdbx runs a real OAuth 2.1 server, so you don't need a key here at all.

In claude.ai, go to Settings → Connectors → Add custom connector.
Enter https://cdbx.ai/api/mcp/server as the URL and save.
claude.ai redirects you to cdbx to log in (if you aren't already) and shows a consent screen listing exactly what it's asking for — this always matches what your account can already do in the cdbx web app, nothing more.
Approve, and you're connected — no key to generate or paste anywhere.

This is standard OAuth (DCR/CIMD under the hood, not a Claude-specific integration), so any other MCP client that supports the same connection flow works the same way — just point it at https://cdbx.ai/api/mcp/server and follow its own login/consent UI.

Available tools

Read (require the MCP Server scope):

Tool	What it does
`list_apps`	Returns your apps — id, name, description, template, access level, timestamps. Supports `limit`, `offset`, and `access` filters.
`read_app_files`	Returns source files from an app. Pass `appId` and optionally a `path` to fetch a single file. For a server-backed app the container must be running.
`get_app_preview`	Returns the live preview for an app — bundled HTML for an instant-runtime app, or the live dev server URL for a server-backed one.
`get_sandbox_embed`	Returns the live public URL and a ready `<iframe>` snippet for a published app — the same URL the in-app Share modal generates. Returns a message instead if it isn't published yet.
`run_code`	Executes code via the cdbx Code Execution API (30 languages — Python, Go, Rust, Java, and more). Requires a key with the separate `runner:execute` scope. Only want code execution, nothing else in your account? Use the standalone Code Execution MCP server instead — same tool, no `mcp:read`/`mcp:write` needed. This is the flagship way to give any agent — including your own — a secure place to run code.
`create_code_session`, `session_write_files`, `session_run`, `session_list_files`, `session_read_files`, `close_code_session`	A persistent code-execution session for an agent iterating on multi-file code — write files, run, read the error, change one file, run again, without re-uploading everything each time. Ephemeral: no preview, doesn't appear in your Apps list, and closes itself after a short idle period. Requires `runner:execute`.
`list_design_systems`	Lists the design systems available to your account — your own, your workspace's, and cdbx's shared catalog — as summaries (name, source, token/component counts).
`get_design_system`	Returns one design system's real values — every token (name/value/group, plus `darkValue` where set) and a summary of its components, patterns, and guidelines.

Write (require the MCP Server (write) scope):

Tool	What it does
`create_app`	Creates a new app from a template (e.g. `react`, `vue`) — or a server-backed one if the template needs a real backend. Returns the id and editor URL.
`create_program`	Creates a Program — a saved compiled-language item (Go, Rust, Java, C#, Python, …) that runs and returns output, no UI. Belongs to Code Execution, not your Apps list.
`start_app`	Wakes a stopped app's container. Needed before `read_app_files`, `get_app_preview`, `write_files`, or `manage_app_packages` will work on an app that's asleep. A no-op if already running.
`manage_app_packages`	Runs `npm install`/`npm uninstall` in a running app's container. No arbitrary shell commands — package names are validated.
`write_files`	Writes files into an app you own. On the instant runtime, only files that already exist can be updated (no new files). For a server-backed app, any path can be written, but its container must be running.
`build_app`	Build a new app from a plain-language description, in one call: infers the right runtime and template, creates it, and runs the cdbx build AI to completion — then returns an editor URL and, if it needs a server, a live preview URL. Runs a real multi-round AI build, so it can take a while, and doesn't support back-and-forth clarification — it makes its best guess from the description you give it. No connectors or database context are passed in for this first build; follow up with `write_files`/`manage_app_packages` for anything further.

Files (also require the MCP Server (write) scope):

On-brand presentable/written output — not code, and not create_app with a template swap. Both take real content directly, so the deck or document is complete in one call.

Tool	What it does
`create_slides`	Creates a Slides deck directly from slide content you provide — each slide is a complete `<section class="slide ...">` HTML element, in the order they should appear. Returns the id and editor URL.
`create_docs`	Creates a Docs document directly from HTML content you provide — semantic HTML with at least one `<h2 id="...">` section (the one required structural rule). Returns the id and editor URL.

Design Systems (write; also requires the MCP Server (write) scope) — list_design_systems/get_design_system above are the read half of this same group:

Tool	What it does
`create_design_system`	Creates a design system directly from token values you provide — the brand colors, fonts, and other tokens that theme Apps, Slides and Docs on-brand. At least one token, component, pattern, or guideline is required.

Access rules

list_apps only returns your own apps.
read_app_files and get_app_preview work for your own apps and any public app.
get_sandbox_embed works for your own apps and any public one, but only once published.
The write tools only ever act on resources you own.

Revoking access

API key: in API → API Keys, click Revoke next to the key. It stops working immediately.

OAuth connection (claude.ai or any other OAuth-based client): in Security → Connected Apps, click Revoke next to the app. This signs it out everywhere at once — you can also disconnect from the client's own side (e.g. claude.ai's connector settings), whichever's easier.

AI Agents MCP Connectors