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

# MCP

> Use MCP to connect Mudstack with Claude, GPT, Cursor, or VSCode and manage assets with AI.

The Model Context Protocol (MCP) integration lets Mudstack connect directly to AI clients like Claude, GPT, Cursor, and VSCode. Once connected, your LLM can securely search, tag, rename, lock, and comment on assets inside your workspaces — all through structured tool calls. Configure the MCP server once, authenticate with your account ID, and your AI will have everything it needs to work with your libraries and projects.

## Setup Instructions

### General

1. Ensure your LLM client supports MCP (Claude Desktop, GPT, Cursor, VSCode).
2. Configure your client’s MCP settings file (examples below).
3. Start the client — you will be prompted for authentication
4. Some clients require a restart after authentication (Claude Desktop).
5. Others (VSCode, Cursor) typically don’t require a restart.

It is important to have your account ID, as every MCP call requires it.

Your account ID is easiest to grab by copying a link from a file in the app.
`https://app.mudstack.com/sh/asset/9c8f1e7a-2d34-4f71-b58c-7e9d2a3f4b10/2e7c4d8a-91f2-4c73-8f6b-1a0e5bc9d432/ab51f7c0-38d2-4e1b-b927-3f68a2cd8e4f`
The account ID is the first ID string in this URL `9c8f1e7a-2d34-4f71-b58c-7e9d2a3f4b10`.

For your first message, write `Get account data for 9c8f1e7a-2d34-4f71-b58c-7e9d2a3f4b10`
You should receieve a summary of your account data if everything is connected properly.

<Tip>
  Once you provide the account ID once, the LLM will remember it. Using the
  get-account-data tool, the LLM can fetch all workspace IDs and metadata. This
  allows you to reference workspaces by name, while the model will infer the
  correct IDs automatically.
</Tip>

### Chat GPT (Web)

1. Click on your profile icon in the bottom left and select `Settings`
2. Click on `Connectors` in the left hand column
3. Click the `Create` button in the top right, and configure the server. The MCP Server URL is `https://mcp.mudstack.com/mcp`, and the authentication is `Oauth`.
4. Trust the aplication and create the server
5. You'll see an authentication window appear. Select `allow`
6. When you are ready to use the server, click the `+` icon, click on `More`, and select `Developer Mode`. Click the dropdown `Add Sources` and select the Mudstack MCP server.

### Claude Desktop

1. The Mudstack MCP Server and many other MCP servers require Node.js to run. Verify your Node.js installation by opening a terminal and running: `node --version`
2. Open Claude Desktop Settings: Click on Claude in your system's menu bar and select `Settings...`
3. Access Developer settings: In the settings window, navigate to the `Developer` tab in the left sidebar. Click the `Edit Config` button to open the configuration file (located at `~/Library/Application\ Support/Claude/claude_desktop_config.json`)
4. Open the file and configure the Mudstack Server
5. A browser window should open, complete the authentication process
6. Restart Claude Desktop

```json theme={null}
{
  "mcpServers": {
    "mudstack": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.mudstack.com/mcp"]
    }
  }
}
```

### VSCode

1. Make sure [mcp is enabled](vscode://settings/chat.mcp.enabled) in your application
2. Run the command `MCP: Add Server` (`Ctrl`+`Shift`+`P` or `CMD`+`Shift`+`P` then search for `MCP: Add Server`)
3. Select `HTTP (HTTP or Server-Sent Events)`
4. For the url enter `https://mcp.mudstack.com/mcp`
5. Name the `Mudstack` and press enter
6. Choose either `Global` or `Workspace` for the install, we recommend `Global`
7. You'll see an authentication window appear. Select `allow`
8. Select `MCP` as the account to sign into `https://mcp.mudstack.com/mcp`
9. For the chat window, make sure your mode is set to `Agent` and the Mudstack MCP tools are selected (click the wrench icon in the bottom right to check this)

```json theme={null}
{
  "servers": {
    "mudstack": {
      "url": "https://mcp.mudstack.com/mcp",
      "type": "http"
    }
  },
  "inputs": []
}
```

### Cursor

1. Open Cursor Settings: Click on Cursor in your system's menu bar and select `Settings -> Cursor Settings`
2. Click on `Tools` in the left hand column
3. If you have no MCP Tools, click `Add Custom MCP`, otherwise click on the `+` button to add a new mcp server
4. Configure the Mudstack mcp server
5. You'll see an authentication window appear. Select `allow`

```json theme={null}
{
  "mcpServers": {
    "mudstack": {
      "url": "https://mcp.mudstack.com/mcp",
      "type": "http"
    }
  }
}
```

OR

```json theme={null}
{
  "mcpServers": {
    "mudstack": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.mudstack.com/mcp"]
    }
  }
}
```

## Available Tools

### `get-account-data`

Gets account information for the provided account ID.

**Parameters:**

* `account_id` (string, required)

**Purpose:** Returns roles, IDs, and workspace information.\
**Use case:** “What workspaces do I have access to?”

***

### `search-assets`

Searches for all assets in a workspace.

**Parameters:**

* `account_id` (string, required)
* `workspace_id` (string, required)
* `folder` (string, optional)
* `library_id` (string, optional)
* `asset` (string, optional)

**Purpose:** Flexible filesystem search. Returns asset IDs and metadata.\
**Use case:** “Find all assets in `/scenes` with ‘car’ in their name.”

***

### `lock-asset`

Locks a specified asset.

**Parameters:**

* `account_id` (string, required)
* `workspace_id` (string, required)
* `asset_id` (string, required)

**Use case:** Batch lock assets for editing.

***

### `unlock-asset`

Unlocks a specified asset.

**Parameters:**

* `account_id` (string, required)
* `workspace_id` (string, required)
* `asset_id` (string, required)

**Use case:** Undo a Lock.

***

### `create-comment`

Adds a comment to an asset.

**Parameters:**

* `account_id` (string, required)
* `workspace_id` (string, required)
* `asset_id` (string, required)
* `content` (string, required)

**Use case:** “Add a ‘looks good!’ comment to all `.jpg` files.”

***

### `get-tags`

Fetches all tags in a workspace.

**Parameters:**

* `account_id` (string, required)
* `workspace_id` (string, required)

**Purpose:** Enables tag-aware tool calls.

***

### `add-tag`

Adds a tag to an asset.

**Parameters:**

* `account_id` (string, required)
* `workspace_id` (string, required)
* `asset_id` (string, required)
* `tag_id` (string, required)

**Use case:** Bulk classification (e.g., add “summer” tag to all `/scenery` images).

***

### `create-tag`

Creates a new tag in the workspace.

**Parameters:**

* `account_id` (string, required)
* `workspace_id` (string, required)
* `tag_name` (string, required)
* `tag_color` (string, optional)

**Use case:** Create tags dynamically for workflows.

***

### `update-tag`

Updates an existing tag in the workspace.

**Parameters:**

* `account_id` (string, required)
* `workspace_id` (string, required)
* `tag_id` (string, required)
* `tag_name` (string, required)
* `tag_color` (string, optional)

**Use case:** Update `Phase-1` tag to `Phase-2`, and change the color to red.

***

### `rename-asset`

Renames a specific asset.

**Parameters:**

* `account_id` (string, required)
* `workspace_id` (string, required)
* `asset_id` (string, required)
* `new_name` (string, required)

**Use case:** Append `-finished` suffix to all assets in `/parts`.

***

### `asset-history`

Gets the version history of an asset.

**Parameters:**

* `account_id` (string, required)
* `workspace_id` (string, required)
* `asset_id` (string, required)
* `num_versions` (integer, optional)

**Purpose:** Summarize commits, renames, reviews, etc.\
**Use case:** “Show all changes on this asset in the last 2 weeks.”

***

### `purge-old-versions`

Deletes old versions of an asset.

**Parameters:**

* `account_id` (string, required)
* `workspace_id` (string, required)
* `asset_id` (string, required)

**Use case:** Clean up all completed assets in `/finished`.

***

### `search-commits`

Search for commits in a specific workspace.

**Parameters:**

* `account_id` (string, required)
* `workspace_id` (string, required)
* `num_commits` (number, optional)

**Use case:** Search for commits with in the last month the name `Robot`.

***

### `get-commit-details`

Get the details of a specific commit

**Parameters:**

* `account_id` (string, required)
* `workspace_id` (string, required)
* `commit_id` (string, required)

**Use case:** Give me a list of changes in the commit `Updated character mesh`.

## FAQs

<AccordionGroup>
  <Accordion title="What do I need to do to authenticate?">
    When you first configure the Mudstack MCP server in your client, you’ll be
    prompted to authenticate. Some clients (Claude Desktop) may require a
    restart afterwards.
  </Accordion>

  <Accordion title="What can I do with the MCP?">
    See the Available Tools section for a complete list. Your access depends on
    your account roles and workspace permissions.
  </Accordion>
</AccordionGroup>