Tools | Masset | Documentation

The Masset MCP Server exposes 8 tools, all of which are read-only. AI clients auto-discover the available tools when a connection is established. The toolset will continue to grow to include more Masset functionality over time.

Search tools

These tools allow you to find assets in your Masset library using different search strategies.

`asset_search`

Search for assets by keyword or meaning and return ranked results with metadata. This is the primary search interface — most clients should use this tool for search workflows. Use get_search_context first when the request depends on taxonomy terms (tags, collections) to understand available values.

Parameter	Type	Required	Description
`query`	string	No	Search query (minimum 2 characters). Optional if filters are provided.
`mode`	string	No	Search mode: `all` (default), `keyword`, or `semantic`.
`orderBy`	string	No	Sort order: `relevance` (default), `updated_at_desc`, `created_at_desc`, `name_asc`, `name_desc`.
`filters`	object	No	Filter object with optional fields: `tags`, `collections`, `mimeTypes`, `createdAfter`, `createdBefore`, `isLinkedAsset`.
`limit`	integer	No	Maximum results to return (default 20, max 50).
`includeMetadata`	boolean	No	Include enriched metadata in each result (default `true`).
`includeContentSnippets`	boolean	No	Include text snippets in match pointers (default `false`).

Required scope: mcp:asset_read

`keyword_search`

Agentic use. This tool is primarily intended for agentic use cases (like Codex or Claude Code) that have the ability to repeatedly call tools.

Search for assets by keyword. Performs case-insensitive substring matching across asset names, descriptions, file names, tag names, collection names, and detected object labels, with full-text search on content (plus substring fallback when needed). Returns a list of matching asset IDs. Use get_asset_metadata to retrieve full details for the returned IDs.

Parameter	Type	Required	Description
`query`	string	Yes	The search query (minimum 2 characters).
`limit`	integer	No	Maximum results to return (default 100, max 500).

Required scope: mcp:asset_read

`semantic_search`

Agentic use. This tool is primarily intended for agentic use cases (like Codex or Claude Code) that have the ability to repeatedly call tools.

Search for assets using semantic (meaning-based) search. Finds content that is conceptually related to the query, even if it doesn’t contain the exact keywords. Returns ranked chunks of content with their asset IDs and relevance scores.

Parameter	Type	Required	Description
`query`	string	Yes	The search query. Natural language works best.
`limit`	integer	No	Maximum result chunks to return (default 50, max 200).

Required scope: mcp:asset_read

`asset_analytics_search`

Rank assets by an analytics metric and return the top results. Use this for requests like “top downloaded assets”, “most viewed content last month”, or “how many times was this asset viewed this year”. You can scope analytics to a specific subset of assets by passing assetIds from asset_search.

Parameter	Type	Required	Description
`metric`	string	Yes	Metric to rank by: `downloads`, `views`, or `shares`.
`start`	string	No	Start of the analytics window in ISO 8601 format. Omit for all-time.
`end`	string	No	End of the analytics window in ISO 8601 format. Omit for all-time.
`audience`	string	No	Audience filter: `external`, `internal`, or `both`.
`assetIds`	string[]	No	List of asset IDs (UUIDs) to limit analytics to (max 50). Omit for global analytics.
`limit`	integer	No	Maximum results to return (default 20, max 50).
`offset`	integer	No	Number of results to skip (default 0).
`includeMetadata`	boolean	No	Include enriched metadata in each result (default `true`).

Required scope: mcp:asset_read + analytics permissions

Asset detail tools

These tools retrieve detailed information about specific assets by their IDs.

`get_asset_metadata`

Retrieve detailed metadata for a list of assets by their IDs. Returns enriched asset information including name, description, file type, size, properties, tags, colors, and more. Maximum of 50 asset IDs per request.

Parameter	Type	Required	Description
`assetIds`	string[]	Yes	List of asset IDs (UUIDs) to retrieve metadata for (max 50).

Required scope: mcp:asset_read

`get_asset_content`

Retrieve the text content of assets by their IDs. Returns extracted text content for each asset. Content is truncated to 50,000 characters per piece with a truncation indicator. Maximum of 10 asset IDs per request.

Content types include:

Raw text
Summaries
OCR text
Transcriptions

Parameter	Type	Required	Description
`assetIds`	string[]	Yes	List of asset IDs (UUIDs) to retrieve content for (max 10).

Required scope: mcp:asset_content_read

`get_asset_preview`

Fetch a JPEG preview image for an asset. Returns text context plus a base64-encoded image that can be displayed inline in AI conversations.

Parameter	Type	Required	Description
`assetId`	string	Yes	Asset ID (UUID) to fetch a preview for.

Required scope: mcp:asset_read

Discovery tools

These tools help you understand the taxonomy and structure of content in your Masset library.

`get_search_context`

Retrieve available search taxonomy for the current tenant. Returns categories and tags, plus collections visible to the current user. Use this before asset_search when you need to map natural-language terms to tag or collection names.

This tool takes no parameters.

Required scope: mcp