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` binary	API key	When you need a local-only connection — air-gapped, custom base URL, or stdio-only clients.

All three speak the same MCP protocol and expose the same tools.

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

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.Example Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "melius": {
      "command": "mel-mcp",
      "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.

​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

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