> ## Documentation Index
> Fetch the complete documentation index at: https://docs.melius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect Claude or another agent to your Melius projects, canvases, and creatives.

The Melius MCP server lets an AI agent (Claude Desktop, Claude Code, 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                                                                                 |
| ---------------------------------- | ---------------------------- | ------------------- | ------------------------------------------------------------------------------------------- |
| **Claude connector** (recommended) | `https://mcp.melius.com/mcp` | Sign in with Melius | One-click connect for Claude — no API key to create or paste.                               |
| Remote HTTP                        | `https://api.melius.com/mcp` | API key             | Default. Works with Claude Desktop, Claude Code, and any HTTP MCP client.                   |
| 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.

<Tabs>
  <Tab title="Connect via Claude (recommended)">
    The Claude 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

    <Steps>
      <Step title="Open Claude">
        Go to **Customize → Connectors → Add (+) → Custom**.
      </Step>

      <Step title="Name your connector">
        Set the name to **Melius**.
      </Step>

      <Step title="Paste the endpoint">
        ```
        https://mcp.melius.com/mcp
        ```
      </Step>

      <Step title="Sign in with Melius">
        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.
      </Step>

      <Step title="Set tool permissions">
        Go to **Tool Permissions** and select **Always Allow** for everything.
      </Step>
    </Steps>

    ### Claude Code

    <Steps>
      <Step title="Add the connector">
        ```bash theme={null}
        claude mcp add melius --transport http https://mcp.melius.com/mcp --scope user
        ```
      </Step>

      <Step title="Authenticate">
        Run `claude`, type `/mcp`, select **melius**, and follow the browser prompt. Sign in to Melius and pick a team.
      </Step>
    </Steps>

    ### 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.
  </Tab>

  <Tab title="Connect with an API key">
    ### 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

    <Steps>
      <Step title="Open Claude">
        Go to **Customize → Connectors → Add (+) → Custom**.
      </Step>

      <Step title="Name your connector">
        Set the name to **Melius**.
      </Step>

      <Step title="Paste the endpoint">
        ```
        https://api.melius.com/mcp
        ```
      </Step>

      <Step title="Paste your API key">
        Use a key from **Team settings → Integrations**. Save the connection.
      </Step>

      <Step title="Set tool permissions">
        Go to **Tool Permissions** and select **Always Allow** for everything.
      </Step>
    </Steps>

    ### Claude Code

    <Steps>
      <Step title="Add the connector">
        ```bash theme={null}
        claude mcp add melius --transport http https://api.melius.com/mcp --scope user
        ```
      </Step>

      <Step title="Authenticate">
        Run `claude`, type `/mcp`, select **melius**, and follow the browser prompt.
      </Step>
    </Steps>

    ### Local stdio (`mel-mcp`)

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

    ```bash theme={null}
    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`:

    ```json theme={null}
    {
      "mcpServers": {
        "melius": {
          "command": "mel-mcp",
          "env": {
            "MEL_API_KEY": "mel_..."
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 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:

1. Call [`file_upload`](/mcp/tools#files) — returns a signed URL.
2. `PUT` the file bytes to the URL.
3. Call [`file_upload_complete`](/mcp/tools#files) — finalizes the asset and creates the file node.

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

<Steps>
  <Step title="Open Organization Settings">
    Go to **Organization Settings → Capabilities → Code execution**.
  </Step>

  <Step title="Enable code execution and egress">
    Turn on **Cloud code execution and file creation** and **Allow network egress**.
  </Step>

  <Step title="Allowlist *.melius.com">
    Add this exactly to the network egress allowlist:

    ```
    *.melius.com
    ```
  </Step>
</Steps>

**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`](/mcp/tools#display). 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.

<Steps>
  <Step title="Open the connector menu">
    Click the triple-dot (**⋯**) menu on the Melius connector in Claude.
  </Step>

  <Step title="Refresh the tools list">
    Select **Refresh** to reload the tools list. The Melius tools appear once the refresh completes.

    <Frame>
      <img src="https://mintcdn.com/melius/cH1oNUe2ZIqtntYT/images/MCP-troubleshoot.png?fit=max&auto=format&n=cH1oNUe2ZIqtntYT&q=85&s=135384beb3e3473a7108acef90df7911" alt="Refresh the tools list from the connector's triple-dot menu" width="1562" height="238" data-path="images/MCP-troubleshoot.png" />
    </Frame>
  </Step>
</Steps>

If the tools still don't appear, confirm your endpoint and credentials are correct (see [Connection options](#connection-options)) and that your connection in Melius hasn't been revoked.

## Full tool reference

See [Tool reference](/mcp/tools) 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 Claude chat history, conversation summaries, Claude 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**. Other MCP-compatible clients work as long as they speak Streamable HTTP MCP.