MCP tool reference

Every tool the AssetHoard MCP server offers, with arguments and responses

Conventions

This page is the reference for the tools an assistant sees once it's connected. To turn the server on and connect a client, see MCP server.

Links. Every asset, bundle and project the tools return carries a link such as assethoard://asset/123. Clicking it focuses AssetHoard and reveals that item. Assistants are told to include these links when pointing you at results.
Errors. Failures such as an unknown id, a bundle inside a package, or write tools being switched off come back as readable messages the assistant can act on.
Common values. file_type is often texture, sprite, model, audio or material. asset_class is often sprite, tileset or model.

Read tools

Always available while the server is on.

Tool	What it does	Arguments
`search`	Search like the app's search bar: by name with typo tolerance and, when semantic search is ready, by meaning. Returns a page of assets, matching bundles and projects, and facet counts across all matches.	`query` (2+ characters; `#tag` limits to a tag, `*.png` to an extension), `file_type`, `asset_class`, `ecosystem` (`godot`, `unity`, `unreal`, `generic`), `category_ids`, `tags` (must have all), `bundle_id` (searches inside a bundle and its sub-bundles), `mode` (`auto`, `text`, `semantic`), `offset`, `limit` (default 20, max 200)
`list_assets`	List assets by filters alone, paged, with a total count.	`name_contains`, `file_type`, `asset_class`, `category_id`, `tags` (any of), `offset`, `limit` (default 50, max 200)
`get_asset`	Full details of one asset: path, type, tags, category, bundle, source package, licence, notes, metadata and whether it has a thumbnail.	`id`
`get_thumbnail`	The asset's preview image (PNG, at most 256px), returned as an image the model can look at.	`id`
`list_bundles`	Bundles under a parent, or the top-level bundles.	`parent_id` (omit for top level)
`get_bundle_contents`	The child bundles and assets directly inside a bundle.	`id`
`list_tags`	All tags with asset counts.	None
`list_categories`	All categories with asset and bundle counts.	None
`list_projects`	All projects with their asset, bundle and package counts.	None
`export`	Copy assets and whole bundles into an existing folder. Bundles keep their folder layout. Referenced files come along by default. Never overwrites: existing files are skipped and reported.	`asset_ids`, `bundle_ids` (at least one of the two), `dest_dir` (absolute path to an existing folder), `with_dependencies` (default true)

Write tools

Available when Allow write tools is on. Every write uses the same code as the matching action in the app, appears in the open window straight away, and can be undone with Ctrl+Z (Cmd+Z on Mac). Undo entries start with MCP:.

Bundles

Tool	What it does	Arguments
`create_bundle`	Create an empty bundle.	`name`, `parent_bundle_id` (omit for top level; can't be inside a package)
`rename_bundle`	Rename a bundle.	`id`, `name`
`move_to_bundle`	Move assets and bundles into a bundle, or to the Library root. An asset lives in one bundle at a time, so this takes it out of its current one. Anything that can't move, such as a bundle into itself, is reported as skipped.	`target_bundle_id` (null for the Library root), `asset_ids`, `bundle_ids`

Tags and categories

Tool	What it does	Arguments
`add_tag`	Tag assets, creating the tag if needed. Tag names are case-insensitive. Members of a variant group are tagged together.	`tag`, `asset_ids`
`remove_tag`	Remove a tag from assets. Members of a variant group change together.	`tag`, `asset_ids`
`set_category`	Set or clear the category of assets. Members of a variant group change together.	`asset_ids`, `category_id` (null clears)
`create_category`	Create a category. Refuses a name that already exists (ignoring case) and returns the existing category's id so the assistant uses that instead.	`name`
`rename_category`	Rename a category.	`id`, `name`
`delete_category`	Delete a category, only if no asset or bundle uses it.	`id`
`update_bundle_categories`	Add and remove categories on bundles. A bundle can have several.	`bundle_ids`, `add_category_ids`, `remove_category_ids`

Projects

Projects record which library items a game uses. They only reference items: nothing moves, and an item can be in several projects.

Tool	What it does	Arguments
`create_project`	Create an empty project.	`name`, `description`
`update_project`	Rename a project and change its description. An empty string clears the description.	`id`, `name`, `description`
`delete_project`	Delete a project, only if it is empty.	`id`
`add_to_project`	Add assets and bundles to a project. Returns the items that were newly added.	`project_id`, `asset_ids`, `bundle_ids`
`remove_from_project`	Remove assets and bundles from a project. They stay in the library.	`project_id`, `asset_ids`, `bundle_ids`

Import

Unless Import without asking is on, you approve each import in the app. See how importing works.

Tool	What it does	Arguments
`import_path`	Import a file or folder from this computer. A folder becomes a bundle named after it, with a sub-bundle per subfolder. Archives and .unitypackage files are indexed in place as packages. Returns an import_id once queued.	`path` (absolute), `target_bundle_id` (omit for the Library root; can't be inside a package)
`get_import_status`	Progress of an import: queued, running, done (with counts and a link to the new bundle), cancelled or failed.	`import_id`

Deliberately left out

No deleting assets or bundles. Category and project deletes only work when they're already empty or unused.
No merging or clearing categories or tags in bulk.
No overwriting files on export.

Response shapes

AssetSummary

Returned in search, list_assets and get_bundle_contents.

{
  "id": 1201,
  "name": "rock_large_01",
  "file_type": "model",
  "extension": "glb",
  "path": "D:/Assets/Env/rock_large_01.glb",
  "in_package": false,
  "size": 482113,
  "tags": ["nature", "lowpoly"],
  "link": "assethoard://asset/1201"
}

Assets inside an archive or .unitypackage have in_package: true and a virtual path.

AssetDetails

Returned by get_asset. Everything in AssetSummary, plus category and bundle (each { "id", "name" } or null), source_package, license, notes, metadata (type-specific, such as dimensions or vertex counts) and has_thumbnail.

BundleSummary

{
  "id": 88,
  "name": "Dungeon Tileset",
  "parent_id": 10,
  "asset_count": 64,
  "child_bundle_count": 3,
  "total_asset_count": 210,
  "link": "assethoard://bundle/88"
}

search

assets, total_assets, offset, bundles, total_bundles, projects ({ id, name }) and facets (file_types, asset_classes, categories keyed by id, and the top 25 tags). Bundles and projects come back on the first page only.

list_assets

items, total and offset.

export

written, skipped and failed (lists of paths), and dest.

get_import_status

One of these, depending on the state. The last 50 imports are remembered.

{ "state": "queued" }
{ "state": "running" }
{ "state": "done", "imported": 412, "packages": 0, "failed": 0,
  "root_bundle_id": 97, "link": "assethoard://bundle/97" }
{ "state": "cancelled", "imported": 120 }
{ "state": "failed", "error": "..." }