Tools

The Masset MCP Server exposes 36 tools spanning search, asset details, asset management, sharing, activity, discovery, content rooms, content requests, and training. Most tools are read-only; the asset management, asset-sharing, content room, content request, and training mutation tools modify state in your Masset workspace. 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.

Required scope: mcp:asset_read

keyword_search

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.

Required scope: mcp:asset_read

semantic_search

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.

Required scope: mcp:asset_read

find_similar_assets

Find assets similar to one or more source assets, ranked by similarity. Similarity blends the source assets’ embedded content (text and visual) with shared tags, so it works across documents, images, videos, presentations, and websites. When multiple source asset IDs are provided, results are similar to the combined theme of all sources. Source assets that have no embedded content yet (for example, still processing) are reported back in sourceAssetIdsWithoutEmbeddings. Use get_asset_metadata to retrieve full details for the returned asset IDs. Results are limited to assets the current user has permission to view.

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.

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.

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

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.

Required scope: mcp:asset_read

Asset management tools

These tools create and modify assets in your Masset library. Unlike the read-only tools above, they change the contents of your workspace.

asset_upload

Upload a new Masset asset. The tool supports three modes, selected with the mode parameter:

• base64 — for files up to 25 MB decoded. Provide fileBase64 and the asset is created synchronously after server-side analysis.
• request_upload_url — for larger files. The tool returns a one-time raw PUT uploadUrl, the required headers, and an expiresAt timestamp 15 minutes out. The PUT response returns the finalized asset after server-side analysis.
• external_link — registers an external URL as an asset with no file bytes. Provide url and optionally name and description. The asset is created and published synchronously.

The response status is one of created, upload_url_created, rejected, or failed.

Required scope: mcp + asset management permissions

asset_new_version

Replace the file behind an existing Masset asset with a new version. The asset keeps its ID, name, description, tags, collections, sharing, and analytics history — only the file and the properties derived from it change. To change an asset’s name, description, or tags without touching its file, use update_asset instead.

The tool supports two modes, selected with the mode parameter:

• base64 — for files up to 25 MB decoded. Provide assetId and fileBase64.
• request_upload_url — for larger files. The tool returns a one-time raw PUT uploadUrl bound to that asset, with a 15 minute expiry. The PUT response returns the updated asset.

Previews, extracted text, and embeddings are rebuilt asynchronously, so they lag the response by a few minutes.

The response status is one of replaced, upload_url_created, rejected, or failed.

Required scope: mcp + asset access permissions (the caller must have EDIT access to the asset)

update_asset

Partially update an existing asset’s metadata. Only the fields you provide change; omitted fields are left untouched. This does not replace the asset or re-process its underlying file. The caller must have EDIT access to the asset, otherwise the response returns an error and nothing is changed.

Sharing and general access are not changed here; use asset_internal_share for that.

Required scope: mcp + asset access permissions (the caller must have EDIT access to the asset)

Sharing tools

These tools modify who can access an asset inside your Masset workspace. (To share content externally via a public link, use the content room tools below.)

asset_internal_share

Share one or more assets internally with users, groups, and optionally the whole organization. Named user and group shares merge into the existing access list — pass userShares / groupShares, each with a shareLevel of VIEW or EDIT. Existing higher direct shares are preserved (and surfaced as warnings) rather than lowered. generalAccessType, when provided, is a full general-access update: RESTRICTED removes organization-wide access, while ORGANIZATION grants it at generalAccessShareLevel. The caller must be allowed to share every asset; if not, the response returns an error for that asset and no sharing changes are applied. Resolve user and group IDs via list_users and list_groups when you only have names.

Required scope: mcp + asset access permissions (the caller must be able to share each target asset)

Activity tools

These tools provide insight into how assets are being used across your organization.

get_asset_activity

Get usage activity (views, downloads, shares) for specific assets, optionally scoped to specific internal users. Returns per-asset counts including zero-activity assets. Use this after resolving asset IDs from list_collections and user IDs from list_groups. The internalUserIds parameter filters internal user events only — external and content room activity is always included.

Required scope: mcp + analytics permissions

Discovery tools

These tools help you understand the taxonomy, structure, and organizational context 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

list_collections

List collections visible to you, with their asset IDs. Use this to resolve a collection name (e.g., “Q1 Launch Materials”) into a list of asset IDs that can be passed to get_asset_activity. Pass a search term to filter by collection name, or omit to list all visible collections.

Required scope: mcp + collections permissions

list_groups

List user groups visible to you, with their member user IDs. Use this to resolve a group name (e.g., “Sales”) into a list of user IDs that can be passed to get_asset_activity. Pass a search term to filter by group name, or omit to list all visible groups.

Required scope: mcp + groups permissions

list_users

Look up user details by ID, or list all users in the company. Use this to resolve user IDs from list_groups into names, or to find users by name or email. Pass userIds to look up specific users, or omit to list all users (optionally filtered by search).

Required scope: mcp + users permissions

list_boards

List boards visible to you, with their names and descriptions. Use this to resolve a board name (e.g., “Q1 Launch Plan”) into a boardId that can be passed to content_room_create or content_room_update. Pass a search term to filter by board name, or omit to list all visible boards.

Required scope: mcp + boards permissions

Content room tools

These tools find, create, and update content rooms — shareable bundles of assets and/or boards that can be associated with HubSpot CRM objects. Content rooms produce a public URL that can be shared with the recipient.

content_room_find

Find content rooms owned by the current user by ID, CRM reference, or free-text CRM lookup. Provide exactly one of: contentRoomId, crmRef, or crmLookup. crmLookup searches synced HubSpot contacts/companies/deals; if it matches multiple objects, the response includes a candidates list and no rooms — call again with crmRef set to one of the candidates to disambiguate. Use this before content_room_create to check whether a room already exists for a given recipient.

Required scope: mcp:content_room_read + content room management permissions

content_room_list

List all content rooms owned by the current user. Each room includes its asset/board IDs, populated CRM references (with HubSpot display names when available), and a publicUrl that can be shared with the recipient. Use content_room_find to locate a single room by ID or CRM association rather than listing them all.

This tool takes no parameters.

Required scope: mcp:content_room_read + content room management permissions

content_room_create

Create a new content room owned by the current user. At least one of assetIds or boardIds must be supplied. A content room may optionally be associated with a CRM object (HubSpot contact, company, or deal). Provide either crmRef (an explicit reference) or crmLookup (a free-text term such as a person’s name) — never both. crmLookup searches synced HubSpot data; if it matches multiple objects, the response includes a candidates list and no room is created. The returned room includes a publicUrl that can be shared with the recipient. Use content_room_find first to check whether an existing room already serves the same recipient.

Required scope: mcp:content_room_write + content room management permissions

content_room_update

Update an existing content room owned by the current user. Asset and board associations merge: addAssetIds/addBoardIds append to the existing set, removeAssetIds/removeBoardIds prune from it. Associations not mentioned are preserved. To replace the full set, supply both add and remove lists. The CRM association is preserved unless you supply a new crmRef/crmLookup or set clearCrm=true. The expiration is preserved unless you supply a new expiresAt or set clearExpiresAt=true. Only the original creator of the room may update it.

Required scope: mcp:content_room_write + content room management permissions

Content request tools

These tools let AI clients submit content requests on behalf of the current user. Requests become tasks that admins or asset owners can act on within the Masset app.

content_request_form_get

Return the custom fields an admin has configured for new-asset requests. Call this before content_request_create with kind="NEW_ASSET" to learn which questions to ask the user.

Each field has an id, label, fieldType (MULTIPLE_CHOICE, DROPDOWN, YES_NO, SHORT_TEXT, or LONG_TEXT), a required flag, and — for choice fields — the selectable options, each with an id and label.

When fields are returned, collect answers and pass them to content_request_create via the answers parameter. When no fields are returned, the company has not configured a custom form; submit a free-text request with fileType and message instead.

This tool takes no parameters.

Required scope: mcp + asset access permissions

content_request_create

Create a Masset content request that becomes a task tracked in the app, routed to the appropriate Masset owner or team.

For kind="NEW_ASSET", always call content_request_form_get first to learn how the company collects new-asset requests. If it returns fields, ask the user those questions and submit the collected answers via answers. If it returns no fields, submit a free-text request with fileType and message instead.

Pass kind="ASSET_CHANGE" together with assetId and changeDescription to ask the asset owner to update an existing asset; the caller must have READ access to the target asset.

The response may come back in one of several states instead of a created task:

• requiresConfirmation=true — an existing asset may already satisfy the request. Show matchCandidates to the user and, only if they still want a new asset, call again with matchAcknowledged=true.
• disabled=true — the company has turned off content requests. No task is created.
• externalLink — the company routes content requests to an external system. No task is created; hand the URL to the user so they can submit the request there.

Required scope: mcp + asset access permissions

Training tools

These tools manage Masset Training — fact-based learning sessions delivered via Slack. The tools cover the full lifecycle: discover sessions, edit DRAFT sessions (sources, facts, questions, manual inputs), AI-generate content, transition through lifecycle states, and read leaderboards and user stats.

training_session_list

List training sessions in the company. Discovery tool — returns lightweight session metadata suitable for choosing a trainingSessionId to pass to training_session_get, training_leaderboard_get, or any of the training write tools.

Required scope: mcp + training management permissions

training_session_get

Get a single training session with its full dashboard: session metadata (status, schedule, audience, duration); summary stats (targeted/mastered/participants/non-responders, attempts, average score); per-fact stats (attempts, completions, mastered users, average score); and per-user progress (total points, completed attempts, mastered fact count, last attempt). Set includeAttempts=true to also include the attempt timeline (large; default off).

Required scope: mcp + training management permissions (READ on session)

training_session_create

Create a new training session in DRAFT status. Returns the new session detail with the generated trainingSessionId — use that ID to attach sources/facts/questions and eventually start the session via training_session_lifecycle. Audience: pass targetUserIds and/or targetGroupIds — at least one is required before the session can start.

Required scope: mcp + training management permissions

training_session_update

Update the metadata, schedule, and audience of a DRAFT training session. Sessions in RUNNING/PAUSED/COMPLETED/CANCELLED status are not editable. Audience replace: targetUserIds and targetGroupIds, when supplied, fully replace the prior audience (not merge). runOnDays, when supplied, fully replaces the prior schedule.

Required scope: mcp + training management permissions (EDIT on session)

training_session_lifecycle

Transition a training session through its lifecycle. Returns ok=true with the new status, or ok=false with errors when the transition is illegal.

Valid actions:

• start: DRAFT → RUNNING (requires at least 1 active fact, 1 active question, and 1 user/group target)
• pause: RUNNING → PAUSED (cancels open attempts)
• resume: PAUSED → RUNNING (extends end time by paused duration)
• complete: RUNNING/PAUSED → COMPLETED
• cancel: any non-COMPLETED → CANCELLED

Required scope: mcp + training management permissions (EDIT on session)

training_sources_manage

Attach or detach a source (asset, collection, or board) on a DRAFT training session. Sources back the AI fact-generation flow (training_generate).

• attach: provide exactly one of assetId / collectionId / boardId.
• detach: provide sourceId (the foreign ID of the asset/collection/board to detach — type is auto-resolved).

Required scope: mcp + training management permissions (EDIT on session)

training_manual_inputs_manage

Create, update, or delete a manual input (free-form text the AI uses for fact generation) on a DRAFT training session.

Required scope: mcp + training management permissions (EDIT on session)

training_facts_manage

Create, update, or delete a fact on a DRAFT training session. Source attribution lists (sourceAssetIds, sourceCollectionIds, sourceBoardIds), when provided on update, replace the prior values; omit a list to leave it untouched. delete is a soft-delete — existing attempts continue to resolve to the fact.

Required scope: mcp + training management permissions (EDIT on session)

training_questions_manage

Create, update, or delete a question on a DRAFT training session. factIds, when provided on update, replaces prior links. Every active question must link to at least one active fact before the session can start.

Required scope: mcp + training management permissions (EDIT on session)

training_generate

AI-generate facts or questions on a DRAFT training session.

• facts_from_source: generates facts from one source (asset/collection/board) attached to the session. Requires sourceId. Idempotent — re-runs add new attribution rather than duplicate facts.
• questions_from_facts: generates questions from the session’s facts. Optional sourceIds to bias generation toward specific sources.

Required scope: mcp + training management permissions (EDIT on session)

training_leaderboard_get

Get the company-wide or session-specific training leaderboard. Each entry includes rank, userId, displayName, email, totalPoints, and currentStreak.

• scope=company (default): top entries across all sessions, with optional caller-context window when the caller sits outside the top.
• scope=session: top entries within a single training session — trainingSessionId is required.

Required scope: mcp + training management permissions (READ on session when scope=session)

training_user_stats_get

Per-user training stats across all sessions in the company. Use this to answer “who is most engaged?”, “who has the longest streak?”, or “what’s user X’s rank?”. Returns for each user: currentStreak, longestStreak, totalPoints, leaderboardRank, totalParticipants, masteredFactCount (cross-session), participatingSessionCount, and lastActivityAt. Resolve user IDs first via list_users / list_groups when you only have names.

Required scope: mcp + training management permissions