MCP Server

Tools

Explore all tools available through the Masset MCP Server

The Masset MCP Server exposes 30 tools spanning search, asset details, activity, discovery, content rooms, content requests, and training. Most tools are read-only; the 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.

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.

ParameterTypeRequiredDescription
querystringNoSearch query (minimum 2 characters). Optional if filters are provided.
modestringNoSearch mode: all (default), keyword, or semantic.
orderBystringNoSort order: relevance (default), updated_at_desc, created_at_desc, name_asc, name_desc.
filtersobjectNoFilter object with optional fields: tags, collections, mimeTypes, createdAfter, createdBefore, isLinkedAsset.
limitintegerNoMaximum results to return (default 20, max 50).
includeMetadatabooleanNoInclude enriched metadata in each result (default true).
includeContentSnippetsbooleanNoInclude text snippets in match pointers (default false).

Required scope: mcp:asset_read

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.

ParameterTypeRequiredDescription
querystringYesThe search query (minimum 2 characters).
limitintegerNoMaximum results to return (default 100, max 500).

Required scope: mcp:asset_read

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.

ParameterTypeRequiredDescription
querystringYesThe search query. Natural language works best.
limitintegerNoMaximum result chunks to return (default 50, max 200).

Required scope: mcp:asset_read

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.

ParameterTypeRequiredDescription
metricstringYesMetric to rank by: downloads, views, or shares.
startstringNoStart of the analytics window in ISO 8601 format. Omit for all-time.
endstringNoEnd of the analytics window in ISO 8601 format. Omit for all-time.
audiencestringNoAudience filter: external, internal, or both.
assetIdsstring[]NoList of asset IDs (UUIDs) to limit analytics to (max 50). Omit for global analytics.
limitintegerNoMaximum results to return (default 20, max 50).
offsetintegerNoNumber of results to skip (default 0).
includeMetadatabooleanNoInclude 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.

ParameterTypeRequiredDescription
assetIdsstring[]YesList 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
ParameterTypeRequiredDescription
assetIdsstring[]YesList 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.

ParameterTypeRequiredDescription
assetIdstringYesAsset ID (UUID) to fetch a preview for.

Required scope: mcp:asset_read

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.

ParameterTypeRequiredDescription
assetIdsstring[]YesAsset IDs (UUIDs) to report on (max 250).
internalUserIdsstring[]NoScope internal events to these user IDs only (max 500). External/content room events are always included unfiltered.
startstringNoStart of the analytics window in ISO 8601 format. Omit for all-time.
endstringNoEnd of the analytics window in ISO 8601 format. Omit for all-time.

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.

ParameterTypeRequiredDescription
searchstringNoFilter collections by name (case-insensitive substring match). 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.

ParameterTypeRequiredDescription
searchstringNoFilter groups by name (case-insensitive substring match). 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).

ParameterTypeRequiredDescription
userIdsstring[]NoSpecific user IDs (UUIDs) to look up (max 500). If omitted, lists all company users.
searchstringNoFilter users by name or email (case-insensitive substring match). Only used when userIds is omitted.

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.

ParameterTypeRequiredDescription
searchstringNoFilter boards by name (case-insensitive substring match). 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.

ParameterTypeRequiredDescription
contentRoomIdstringNoSpecific content room ID (UUID) to fetch.
crmRefobjectNoExplicit CRM reference: crmType=HUBSPOT, crmObjectType=CONTACT | COMPANY | DEAL, crmObjectId=remote HubSpot ID.
crmLookupstringNoFree-text CRM lookup (e.g., “John Smith”). Returns rooms associated with the matched HubSpot object.

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.

ParameterTypeRequiredDescription
namestringNoDisplay name for the content room.
assetIdsstring[]NoAsset IDs (UUIDs) to associate with the new room.
boardIdsstring[]NoBoard IDs (UUIDs) to associate with the new room.
crmRefobjectNoExplicit CRM reference. Mutually exclusive with crmLookup.
crmLookupstringNoFree-text CRM lookup. Mutually exclusive with crmRef.
expiresAtstringNoOptional expiration timestamp (ISO 8601) for the public link.
notificationsEnabledbooleanNoWhether owner notifications should fire for this room (default true).

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.

ParameterTypeRequiredDescription
contentRoomIdstringYesID (UUID) of the content room to update.
namestringNoNew display name for the content room.
addAssetIdsstring[]NoAsset IDs (UUIDs) to add to the room.
removeAssetIdsstring[]NoAsset IDs (UUIDs) to remove from the room.
addBoardIdsstring[]NoBoard IDs (UUIDs) to add to the room.
removeBoardIdsstring[]NoBoard IDs (UUIDs) to remove from the room.
crmRefobjectNoReplacement CRM reference. Mutually exclusive with crmLookup and clearCrm.
crmLookupstringNoFree-text CRM lookup. Mutually exclusive with crmRef and clearCrm.
clearCrmbooleanNoSet true to remove any existing CRM association. Mutually exclusive with crmRef and crmLookup.
expiresAtstringNoNew expiration timestamp (ISO 8601). Mutually exclusive with clearExpiresAt.
clearExpiresAtbooleanNoSet true to remove any existing expiration (make the public link permanent). Mutually exclusive with expiresAt.

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_create

Create a Masset content request that becomes a task tracked in the app. Pass kind="NEW_ASSET" together with fileType and message to ask Masset admins to add a new asset. 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.

ParameterTypeRequiredDescription
kindstringYesRequest kind: NEW_ASSET or ASSET_CHANGE.
fileTypestringNoFile type for the requested new asset (e.g., pdf, mp4). Required when kind=NEW_ASSET.
messagestringNoFree-text message describing the new asset request. Required when kind=NEW_ASSET.
assetIdstringNoExisting asset UUID to request a change against. Required when kind=ASSET_CHANGE.
changeDescriptionstringNoFree-text description of the requested change. Required when kind=ASSET_CHANGE.

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 write tools require the calling user to have EDIT permission on the target training session. Only DRAFT sessions are editable for content mutations; lifecycle transitions are governed by the rules described under training_session_lifecycle.

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.

ParameterTypeRequiredDescription
statusstringNoOptional status filter (case-insensitive): draft, running, paused, completed, or cancelled.

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).

ParameterTypeRequiredDescription
trainingSessionIdstringYesTraining session ID (UUID).
includeAttemptsbooleanNoInclude the full attempt timeline (default false; large response).

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.

ParameterTypeRequiredDescription
titlestringYesDisplay title for the session.
durationDaysintegerYesNumber of days the session runs (1–365).
descriptionstringNoOptional description shown in the editor.
runOnDaysstring[]NoDays of the week the session runs. Uppercase weekday names (MONDAY..SUNDAY). Defaults to MONDAY–FRIDAY.
targetUserIdsstring[]NoUser IDs (UUIDs) to enroll directly.
targetGroupIdsstring[]NoGroup IDs (UUIDs) to enroll (members are expanded at delivery time).

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.

ParameterTypeRequiredDescription
trainingSessionIdstringYesTraining session ID (UUID).
titlestringYesDisplay title for the session.
durationDaysintegerYesNumber of days the session runs (1–365).
descriptionstringNoOptional description. Omit to preserve the current value; pass an empty string to clear it.
runOnDaysstring[]NoDays of the week the session runs (uppercase weekday names).
targetUserIdsstring[]NoUser IDs (UUIDs). Replaces prior list.
targetGroupIdsstring[]NoGroup IDs (UUIDs). Replaces prior list.

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
ParameterTypeRequiredDescription
trainingSessionIdstringYesTraining session ID (UUID).
actionstringYesLifecycle action: start, pause, resume, complete, or cancel.

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).
ParameterTypeRequiredDescription
trainingSessionIdstringYesTraining session ID (UUID).
actionstringYesattach or detach.
assetIdstringNoAsset ID (UUID). Use for action=attach with an asset.
collectionIdstringNoCollection ID (UUID). Use for action=attach with a collection.
boardIdstringNoBoard ID (UUID). Use for action=attach with a board.
sourceIdstringNoSource foreign ID to detach. Required for action=detach.

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.

ParameterTypeRequiredDescription
trainingSessionIdstringYesTraining session ID (UUID).
actionstringYescreate, update, or delete.
manualInputIdstringNoManual input ID (UUID). Required for update/delete.
contentsstringNoFree-form text contents. Required for create/update.

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.

ParameterTypeRequiredDescription
trainingSessionIdstringYesTraining session ID (UUID).
actionstringYescreate, update, or delete.
trainingSessionFactIdstringNoFact ID (UUID). Required for update/delete.
textstringNoFact text. Required for create/update.
sourceAssetIdsstring[]NoSource asset IDs to attribute the fact to.
sourceCollectionIdsstring[]NoSource collection IDs.
sourceBoardIdsstring[]NoSource board IDs.
originstringNoMANUAL (default) or GENERATED.
isActivebooleanNoWhether the fact is active in the question pool (default true).
displayOrderintegerNoDisplay order (0-indexed). Optional on update.

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.

ParameterTypeRequiredDescription
trainingSessionIdstringYesTraining session ID (UUID).
actionstringYescreate, update, or delete.
trainingSessionQuestionIdstringNoQuestion ID (UUID). Required for update/delete.
textstringNoQuestion text. Required for create/update.
factIdsstring[]NoFact IDs (UUIDs) the question covers (active facts only).
originstringNoMANUAL (default) or GENERATED.
isActivebooleanNoWhether the question is active (default true).
displayOrderintegerNoDisplay order. Optional on update.

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.
ParameterTypeRequiredDescription
trainingSessionIdstringYesTraining session ID (UUID).
actionstringYesfacts_from_source or questions_from_facts.
sourceIdstringNoSource ID (UUID). Required for facts_from_source.
sourceIdsstring[]NoOptional source IDs to bias question generation.
maxFactsintegerNoMax facts to request (1–100, default 12).
maxQuestionsintegerNoMax questions to request (1–100, default 12).

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.
ParameterTypeRequiredDescription
scopestringNocompany (default) or session.
trainingSessionIdstringNoTraining session ID (UUID). Required when scope=session.
limitintegerNoMaximum number of top entries (default 10, max 100).
includeUserContextbooleanNoInclude caller context window when scope=company (default true).

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.

ParameterTypeRequiredDescription
userIdsstring[]YesUser IDs (UUID strings) to look up (max 100).

Required scope: mcp + training management permissions