MCP server - Melius docs

The Melius MCP server lets an AI agent (Claude, ChatGPT desktop, Codex, or any MCP-compatible client) read and write to your projects: create canvases, drop nodes, wire edges, run generations, upload files, and download outputs — all without leaving the agent chat.

Connection options

Connection	Endpoint	Auth	When to use
Melius connector (recommended)	`https://mcp.melius.com/mcp`	Sign in with Melius	One-click connect for Claude, ChatGPT desktop, and Codex — no API key to create or paste.
Remote HTTP	`https://api.melius.com/mcp`	API key	Clients with no OAuth flow, and headless setups (CI, servers).
Local stdio	`mel-mcp --hosted`	API key	Stdio-only clients, including Cast, through your configured backend.

All three use the hosted MCP tool catalog. The older direct REST mode (mel-mcp without --hosted) supports canvas tools and local file uploads, but does not support Cast.

Connect via Claude (recommended)
Connect ChatGPT & Codex
Connect with an API key

The Melius connector signs you in with your Melius account — no API key to paste. Use this for Claude.ai, Claude Desktop, and Claude Code.

Connect Claude Desktop

Open Claude

Go to Customize → Connectors → Add (+) → Custom.

Name your connector

Set the name to Melius.

Paste the endpoint

https://mcp.melius.com/mcp

Claude opens a Melius login page in your browser. Sign in (or use your existing session), pick the team you want Claude to work in, and click Authorize. Melius creates a connector key for Claude on your behalf — you don’t need to create or paste anything. Claude is connected immediately.

Set tool permissions

Go to Tool Permissions and select Always Allow for everything.

Claude Code

Add the connector

claude mcp add melius --transport http https://mcp.melius.com/mcp --scope user

Authenticate

Run claude, type /mcp, select melius, and follow the browser prompt. Sign in to Melius and pick a team.

Disconnect

The connector key Melius created during authorize is listed in Team settings → Integrations under your API keys, named claude-…-mcp. To remove Claude’s access at any time, delete that row. Claude loses access immediately.

The ChatGPT desktop app, the Codex CLI, and the Codex IDE extension share one MCP configuration (~/.codex/config.toml). Set Melius up in any one of them and the other two pick it up.These clients use the same Melius connector as Claude: you sign in with your Melius account and there is no API key to paste.

ChatGPT desktop app

Open plugins

Go to Settings → Plugins → Add MCP server.

Name the server

Set Name to Melius.

Choose the type

Set Type to Streamable HTTP.

Paste the URL

https://mcp.melius.com/mcp

Save the server.

Melius opens a login page in your browser. Sign in (or use your existing session), pick the team you want the agent to work in, and click Authorize. Melius creates a connector key on your behalf — you don’t need to create or paste anything.

Codex CLI

codex mcp add only registers local stdio servers, so add the remote Melius server to ~/.codex/config.toml yourself:

[mcp_servers.melius]
url = "https://mcp.melius.com/mcp"

Then sign in:

codex mcp login melius

Codex opens the Melius authorize page in your browser. Pick a team, click Authorize, and Codex stores the credential. Run codex mcp list to confirm, or type /mcp in the Codex TUI.To scope Melius to a single repo instead of your whole machine, put the same block in that project’s .codex/config.toml.Codex asks before each tool call by default. To let it run Melius tools without prompting — the equivalent of Claude’s Always Allow — add default_tools_approval_mode to the same block:

[mcp_servers.melius]
url = "https://mcp.melius.com/mcp"
default_tools_approval_mode = "auto"

Codex IDE extension

Open MCP servers

Open the gear menu and select MCP servers → Add server.

Fill in the server

Name it Melius, choose Streamable HTTP, and paste https://mcp.melius.com/mcp.

Restart and authenticate

Save the server and select Restart extension, then select Authenticate to sign in with Melius.

Headless setups

Where a browser sign-in isn’t possible (CI, a remote box, a container), skip OAuth and pass an API key from Team settings → Integrations as a bearer token:

[mcp_servers.melius]
url = "https://api.melius.com/mcp"
bearer_token_env_var = "MEL_API_KEY"

Codex reads the key from the MEL_API_KEY environment variable, so the key itself never lands in the config file.

Disconnect

The connector key Melius created during authorize is listed in Team settings → Integrations under your API keys, named after the client that connected (codex-…-mcp). Delete that row to revoke access immediately.

API Keys

Generate an API key from Team settings → Integrations in the Melius app. Each key:

Is shown once at creation time — copy it before closing the modal.
Can be named (Claude, prod-bot, etc.).
Is scoped to a single team.
Can be given an expiry or marked no expiry.
Can be revoked at any time from the same settings page.

Connect Claude Desktop

Open Claude

Go to Customize → Connectors → Add (+) → Custom.

Name your connector

Set the name to Melius.

Paste the endpoint

https://api.melius.com/mcp

Paste your API key

Use a key from Team settings → Integrations. Save the connection.

Set tool permissions

Go to Tool Permissions and select Always Allow for everything.

Claude Code

Add the connector

claude mcp add melius --transport http https://api.melius.com/mcp --scope user

Authenticate

Run claude, type /mcp, select melius, and follow the browser prompt.

Local stdio (`mel-mcp`)

mel-mcp ships with the Melius CLI. Configure your MCP client to run the binary with the right env:

MEL_API_KEY=mel_...   # required
MEL_BASE_URL=https://api.melius.com   # optional; override for self-hosted
mel-mcp --hosted

If MEL_API_KEY isn’t set, mel-mcp falls back to ~/.mel/config.json (the file mel auth login writes). MEL_BASE_URL defaults to https://api.melius.com. With --hosted, the binary forwards to that backend’s /mcp endpoint, which must be running. Attachment uploads use your client’s file-transfer support.Example Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "melius": {
      "command": "mel-mcp",
      "args": ["--hosted"],
      "env": {
        "MEL_API_KEY": "mel_..."
      }
    }
  }
}

Verify the connection

In a new chat, send:

“Create a new project called Hello World in Melius”

If the agent calls project_create and reports a new project ID, you’re connected.

Uploading images

Image upload is a three-step flow:

Call file_upload — returns a signed URL.
PUT the file bytes to the URL.
Call file_upload_complete — finalizes the asset and creates the file node.

In a sandboxed Claude environment, the sandbox must allow network egress to *.melius.com:

Open Organization Settings

Go to Organization Settings → Capabilities → Code execution.

Enable code execution and egress

Turn on Cloud code execution and file creation and Allow network egress.

Allowlist *.melius.com

Add this exactly to the network egress allowlist:

*.melius.com

Video uploads are not supported. Video has to be generated on the canvas via a video node — agents should not attempt to upload .mp4 files.

Inline canvas previews

The MCP server can render a live image of the canvas inline in the agent chat via display_canvas. Useful for confirming layout before the agent commits to a big bulk-run.

Troubleshooting

Melius tools aren’t showing up

If your agent reports “Melius tools aren’t available through the connected MCP servers” or in Claude connectors you see “This connector has no tools available,” the client connected before the tool list finished loading. Refresh the tools list to fix it.

Open the connector menu

Click the triple-dot (⋯) menu on the Melius connector in Claude.

Refresh the tools list

Select Refresh to reload the tools list. The Melius tools appear once the refresh completes.

There is no equivalent refresh in ChatGPT desktop or Codex — restart the client instead. In ChatGPT desktop, quit and reopen the app; in the Codex IDE extension, select Restart extension; for the Codex CLI, quit and relaunch codex. If the tools still don’t appear, confirm your endpoint and credentials are correct (see Connection options) and that your connection in Melius hasn’t been revoked. codex mcp login melius completes the sign-in in a browser on the same machine. On a remote box or in a container, use an API key as a bearer token instead — see Headless setups in the ChatGPT & Codex tab above.

Full tool reference

See Tool reference for every tool and what it does.

Data and permissions

The Melius MCP server reads from and writes to your Melius account. Specifically:

Reads your projects, canvases, nodes, edges, runs, comments, presets, teams, and models you have access to.
Writes new projects, canvases, nodes, edges, runs, uploads, comments, and team skills you ask it to create.
Deletes projects, canvases, nodes, and edges you ask it to delete.
Generates images, video, audio, and text on the canvas via Melius’s existing third-party model providers. All generation is initiated by explicit tool calls.
Does not read your chat history, conversation summaries, agent memory, or files outside the canvas. The server only operates on data the agent provides through tool calls and the canvases it explicitly opens.

The connector is scoped to the single Melius team you pick during authorize.

External links and origins

The display_canvas MCP App opens links to your Melius canvas via ui/open-link. The only origin it opens is the Melius web app:

https://app.melius.com/projects/*/canvas/*

Tested surfaces

The Melius MCP server is tested with Claude.ai, Claude Desktop, and Claude Code. The ChatGPT desktop app, the Codex CLI, and the Codex IDE extension connect over the same Streamable HTTP and OAuth flow. Other MCP-compatible clients work as long as they speak Streamable HTTP MCP.

Cast

Connect to the hosted Melius MCP server and describe the video you want. Name an existing avatar—“make a UGC video of Loopy talking about chemistry class”—to use it directly without a picker. If you haven’t chosen an avatar, browse the library or create four candidates and select your favorite. Your agent writes the script in chat and infers the generation settings from your request. Confirm your avatar in the inline picker. It collapses to a card showing the avatar you selected. If your client puts the selection message in the chat box, press Send to continue. Your agent uses that choice before preparing the script; it does not pick a different avatar while waiting. Generation uses your client’s native MCP tool approval. With auto-approve enabled, an explicit request such as “make 10 videos using Loopy” runs without extra Generate clicks. Draft-only requests stop at the script. The agent waits for each requested video and shows its finished result with Download video. The default is Seedance 2.5, Auto voice and portrait video. You can override supported settings in chat, such as “make it horizontal, 1080p, with subtitles and my saved voice.” Explicit model, resolution, aspect ratio, subtitles and voice requests take priority; the agent infers the remaining settings. Voice, background, prop and template pickers appear only when you ask for them. Otherwise, the agent uses your brief, an automatic voice and scene, and any supplied selections or attachments. MCP Apps clients show avatar choices and the finished video with Download video inline. Other clients receive numbered choices and media links. Attachments require file access and transfer support in your client. See Cast tools.

Batches

Ask explicitly for Cast, for example: “Create 10 Cast videos using Loopy, each visiting a different European city.” Your agent prepares one review with all scripts, settings and the total estimated credits. Native MCP permission approves the batch, including your client’s automatic approval setting. One batch card shows every video, ready/failed/pending counts, individual downloads and View all in Cast. If the server connection is interrupted, the card reports that current status is unknown and retries. It never generates replacements. Batches support up to 20 videos per request and retain normal credit and queue limits. Accepted videos keep running after a disconnect; unsubmitted items are reported separately.

​Connection options

​Connect Claude Desktop

​Claude Code

​Disconnect

​ChatGPT desktop app

​Codex CLI

​Codex IDE extension

​Headless setups

​Disconnect

​API Keys

​Connect Claude Desktop

​Claude Code

​Local stdio (mel-mcp)

​Verify the connection

​Uploading images

​Inline canvas previews

​Troubleshooting

​Melius tools aren’t showing up

​Codex can’t sign in

​Full tool reference

​Data and permissions

​External links and origins

​Tested surfaces

​Cast

​Batches

Connection options

Connect Claude Desktop

Claude Code

Disconnect

ChatGPT desktop app

Codex CLI

Codex IDE extension

Headless setups

Disconnect

API Keys

Connect Claude Desktop

Claude Code

Local stdio (`mel-mcp`)

Verify the connection

Uploading images

Inline canvas previews

Troubleshooting

Melius tools aren’t showing up

Codex can’t sign in

Full tool reference

Data and permissions

External links and origins

Tested surfaces

Cast

Batches