Iconik MCP Server – Setup & Documentation

General Setup Instructions

Every request to the server carries an Authorization: Bearer <token> header. There are two ways to get that token, and the choice decides which iconik user the agent acts as.

OAuth. You sign in through a browser and the client keeps the token. The connection acts as you, with your roles and ACLs, limited to the scopes granted to the OAuth application. Everyone connects as themselves.
Application token. You paste a token into the client's configuration. The connection acts as the user the application was created for, whoever runs the client, and gets that user's full roles and ACLs. Application tokens carry no scopes, so everyone holding the token shares one identity.

Use OAuth when the client supports it. Clients without OAuth support use an application token instead, and those that cannot set request headers themselves use the mcp-remote npx bridge to add it.

The MCP endpoint is:

https://app.iconik.io/mcp/mcp

Get your API token — In Iconik, go to Admin → Settings → Application Tokens and create a new Application and Token. Replace <AUTH-TOKEN> in the snippets below with that Application Token. Keep it secret — treat it like a password.
See Application tokens in the help docs. You don't need to specify the Application ID, that is automatic.

Claude

Claude Desktop

Recommended: OAuth — Claude Desktop can connect directly, without a token or the mcp-remote bridge:

In iconik, go to Admin → Settings → Applications and create a new application.
Choose Browser or device app — no client secret is generated or needed for this flow.
Give it a name, set the Redirect URI to https://claude.ai/api/mcp/auth_callback, and add the scopes Claude should have — at least assets:read and collections:read. Note: user_impersonation gives access to everything you have access to, so only add it if that's intended.
Click Create and copy the Application ID shown — you'll need it in the next step.
In Claude Desktop, open Settings → Connectors → Add custom connector, enter the server URL: https://app.iconik.io/mcp/mcp
Click Connect and sign in to iconik in the browser window that opens — you'll be prompted for a Client ID, which is the Application ID from the previous step.

Alternative: Bearer token — add the following entry to your claude_desktop_config.json file. On macOS it lives at ~/Library/Application Support/Claude/claude_desktop_config.json.

{
  "mcpServers": {
    "iconik": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://app.iconik.io/mcp/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <AUTH-TOKEN>"
      }
    }
  }
}

Claude Code

Claude Code only supports OAuth via dynamic client registration, which the server doesn't support yet, so use a Bearer token instead. Run the following command in your terminal, replacing <AUTH-TOKEN> with your API token:

claude mcp add --transport http iconik https://app.iconik.io/mcp/mcp \
  --header "Authorization: Bearer <AUTH-TOKEN>"

Visual Studio Code

Add the iconik server to your mcp.json file. Run MCP: Open User Configuration from the Command Palette (Ctrl/Cmd Shift P) to open the file, then add the following inside "servers":

{
  "servers": {
    "iconik": {
      "type": "http",
      "url": "https://app.iconik.io/mcp/mcp",
      "headers": {
        "Authorization": "Bearer <AUTH-TOKEN>"
      }
    }
  }
}

Replace <AUTH-TOKEN> with your iconik auth token. To keep it out of the file, use an environment variable instead:

{
  "servers": {
    "iconik": {
      "type": "http",
      "url": "https://app.iconik.io/mcp/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ICONIK_AUTH_TOKEN}"
      }
    }
  }
}

Or use the guided flow:

Press Ctrl/Cmd Shift P and run MCP: Add Server.
Select HTTP or Server-Sent Events.
Enter the server URL: https://app.iconik.io/mcp/mcp
Name the server iconik and press Enter.
Open the generated mcp.json entry and add your token to the "headers" field as shown above.

Cursor

Open Cursor Settings → MCP (or Ctrl/Cmd , and search for MCP), then add the following configuration:

{
  "mcpServers": {
    "iconik": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://app.iconik.io/mcp/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <AUTH-TOKEN>"
      }
    }
  }
}

Zed

Zed supports passing HTTP headers directly, so no bridge is needed. Press Cmd , to open settings and add:

{
"context_servers": {
    "iconik": {
        "enabled": true,
        "url": "https://app.iconik.io/mcp/mcp",
        "headers": {
            "Authorization": "Bearer <AUTH-TOKEN>"
        }
    }
}

Other clients

Any MCP-compatible client can connect to the Iconik MCP server. Use whichever approach your client supports:

Native HTTP transport (preferred)

If your client supports native Streamable HTTP or SSE transport, configure it with:

URL: https://app.iconik.io/mcp/mcp
Header: Authorization: Bearer <AUTH-TOKEN>

stdio via mcp-remote bridge

For clients that only support stdio, use the mcp-remote npx bridge to proxy the connection:

Command: npx
Args: mcp-remote https://app.iconik.io/mcp/mcp --header Authorization: Bearer <AUTH-TOKEN>

Node.js required — The mcp-remote bridge requires Node.js 18 or later. If you see connection errors, try clearing cached auth data: rm -rf ~/.mcp-auth

Available tools

The following tools are exposed by this MCP server. They are discovered automatically from the live server configuration and reflect exactly what is available to your AI agent. Click any tool to expand its full description and parameter reference.

get_asset_file_download_url Files Get a signed download URL for an asset file.

Get a signed download URL for an asset file. Resolves the requested format (default: ORIGINAL) to find the file and returns a time-limited URL that can be used to download it. Use this when a user wants to download or access the actual file content of an asset. Performs three sequential calls: (1) resolve the format name to a format ID, (2) list the files belonging to that format, (3) fetch a signed download URL for the first available file.

Parameters

Name	Type	Required	Description
asset_id	string	required	UUID of the asset whose file you want to download.
format_name	string	optional	Name of the format to download. Defaults to 'ORIGINAL'. Common values: 'ORIGINAL', 'PPRO_PROXY', 'EDIT_PROXY', 'SUBTITLES'.

get_asset_proxy_download_url Files Get a signed download URL for an asset proxy (video/audio preview).

Get a signed download URL for an asset proxy (video/audio preview). Lists the proxies available for the asset and returns a time-limited download URL for the first one. Use this when a user wants to preview or download a proxy rendition rather than the original file. Performs two sequential calls: (1) list the proxies available for the asset, (2) fetch a signed download URL for the first proxy found.

Parameters

Name	Type	Required	Description
asset_id	string	required	UUID of the asset whose proxy you want to download.

get_asset_segments Segments Fetch segments for an asset with optional filtering by type, time range, and free-text query.

Fetch segments for an asset with optional filtering by type, time range, and free-text query. Valid segment types: COMMENT, TAG, TRANSCRIPTION, SCENE, PERSON, MARKER, QC, GENERIC. Use get_asset_transcriptions instead when you specifically want transcription text.

Parameters

Name	Type	Required	Description
asset_id	string	required	UUID of the asset to fetch segments for.
segment_type	string	optional	Filter by segment type. One of: COMMENT, TAG, TRANSCRIPTION, SCENE, PERSON, MARKER, QC, GENERIC.
transcription_id	string	optional	Filter by a specific transcription ID. Use together with segment_type='TRANSCRIPTION'.
query	string	optional	Free-text search within segment content.
time_start_milliseconds__gte	integer	optional	Only return segments starting at or after this timestamp (ms).
time_end_milliseconds__lte	integer	optional	Only return segments ending at or before this timestamp (ms).
per_page	integer	optional	Number of segments per page (default 25, max 100).
page	integer	optional	Page number to fetch (default 1).

get_asset_transcriptions Segments Fetch transcription segments for an asset.

Fetch transcription segments for an asset. First discovers available transcriptions (and their languages), then returns the segments for the requested transcription. If the asset has multiple transcriptions in different languages, pass transcription_id to select one; otherwise the first available transcription is used. Performs up to three sequential calls: (1) fetch the asset to resolve the latest active version ID, (2) list transcription properties for that version, (3) fetch transcription segments filtered by the selected transcription ID.

Parameters

Name	Type	Required	Description
asset_id	string	required	UUID of the asset whose transcription you want.
transcription_id	string	optional	UUID of a specific transcription to fetch. If omitted the first available transcription is used.
query	string	optional	Free-text search within transcription segment content.
time_start_milliseconds__gte	integer	optional	Only return segments starting at or after this timestamp (ms).
time_end_milliseconds__lte	integer	optional	Only return segments ending at or before this timestamp (ms).
per_page	integer	optional	Number of segments per page (default 50, max 100).
page	integer	optional	Page number to fetch (default 1).

get_current_user Auth Return information about the currently authenticated user.

Return information about the currently authenticated user. Call this once after connecting to discover whether the user is an admin, which system domain they belong to, and which groups they are a member of. Clients can use the `is_admin` flag to skip permission checks that are irrelevant for administrators. Data is sourced entirely from the AccessToken populated during MCP authentication – no additional iconik API calls are made.

get_groups_basic Users Return a lightweight list of groups for ID-to-name resolution.

Return a lightweight list of groups for ID-to-name resolution. Depending on group_type this tool calls one of: GET /users/v1/groups/basic/ (untyped groups, default); GET /users/v1/teams/basic/ (teams); GET /users/v1/role_groups/basic/ (role groups); GET /users/v1/groups/all/basic/ (all group types, admin only). Each object contains id, name, alias, description and group_type.

Parameters

Name	Type	Required	Description
page	integer	optional	Which page to fetch (1-based, default 1).
per_page	integer	optional	Number of groups per page (1-100, default 10).
query	any	optional
ids	any	optional
name	any	optional
group_type	any	optional

get_users_basic Users Return a lightweight list of users for ID-to-name resolution.

Return a lightweight list of users for ID-to-name resolution. Calls GET /users/v1/users/basic/ and returns each user's id, first_name, last_name, email and photo.

Parameters

Name	Type	Required	Description
page	integer	optional	Which page to fetch (1-based, default 1).
per_page	integer	optional	Number of users per page (1-100, default 10).
query	any	optional
ids	any	optional
emails	any	optional
status	any	optional
first_name	any	optional
last_name	any	optional
email	any	optional

query_iconik_apps Apps Query Iconik apps (App-IDs) and their tokens (read-only).

Query Iconik apps (App-IDs) and their tokens (read-only). An app in iconik is an API client identity – the App-ID that integrations, scripts and OAuth clients present alongside a token. Each app is either type 'PAT' (a personal-access-token app, the usual choice for scripts and integrations) or 'OAUTH' (an OAuth client with redirect URIs). Use this to answer questions about which integrations exist on the domain, what scopes an app is allowed to request, which user an app acts as by default, and which tokens exist against an app – including when they were created, when they expire, whose they are and whether they carry admin rights. This makes it useful for auditing stale integrations and expiring credentials. Listing your own tokens needs no extra permission; anything app-related requires the apps:read permission and returns a clear error when you do not have it. Token secrets are never returned: the endpoints used here omit them, and any credential-shaped field is redacted before the result is returned. These listings page with a cursor, not page numbers: pass the id of the last object you saw as last_id to fetch the next page. This tool is read-only; it cannot create, update, revoke or delete apps or tokens.

Parameters

Name	Type	Required	Description
operation	string	required	The operation to perform. Options: 'list_apps' – list the apps (App-IDs) configured on the domain; 'get_app' – one app in full (requires app_id); 'list_app_tokens' – the tokens issued against one app, without their secret values (requires app_id); 'list_my_tokens' – the tokens belonging to the authenticated user, without their secret values (no extra permission needed).
app_id	any	optional
per_page	any	optional
last_id	any	optional

query_iconik_collections Collections Query Iconik collections and their contents.

Query Iconik collections and their contents. Provides access to Iconik's collection system, allowing you to list all collections, get details about a specific collection, list contents of a collection (assets and sub-collections), find which collections contain a specific asset, or get aggregated information about a collection's content (asset count, total size, total duration). IMPORTANT: Do NOT mention collection IDs unless explicitly asked by the user. Format collection names as clickable links: [Collection Name](https://app.iconik.io/collection/{collection_id}). For 3 or fewer items, display thumbnails using the thumbnail_url from results. Focus on collection names, descriptions, and relevant metadata in your response.

Parameters

Name	Type	Required	Description
operation	string	required	The collection operation to perform. Options: 'list_collections' – get all available collections; 'get_collection' – get details about a specific collection (requires collection_id); 'list_collection_contents' – list assets and sub-collections in a collection (requires collection_id); 'get_asset_collections' – find which collections contain a specific asset (requires asset_id); 'get_collection_content_info' – get aggregated information about a collection's content, including asset/sub-collection counts, total file size, and total duration (requires collection_id).
collection_id	string	optional	UUID of the collection (for collection-specific queries).
asset_id	string	optional	UUID of the asset (for finding which collections contain it).
page	integer	optional	Page number for pagination (default: 1).
per_page	integer	optional	Number of results per page.
include_subcollections	boolean	optional	For 'get_collection_content_info': whether to include assets from sub-collections when computing totals (default: True).
format_name	string	optional	For 'get_collection_content_info': compute total size only for files with the specified format name (default: 'ORIGINAL').
by_storage_id	boolean	optional	For 'get_collection_content_info': whether to group size results by storage ID (default: True).

query_iconik_jobs Jobs Query Iconik jobs (read-only) to inspect what the system is doing now and what it did before.

Query Iconik jobs (read-only) to inspect what the system is doing now and what it did before. Use this to answer questions about job status and progress, why a job failed, which jobs ran against a particular asset or collection, and how many jobs of each kind succeeded or failed. Job statuses: READY, STARTED, FINISHED, FINISHED_WITH_WARNING, FAILED, WAITING, ABORT_PENDING, ABORTED, SKIPPED, PAUSED, PENDING_USER, DISCARDED. A job's individual steps arrive inline on the job object as 'steps', so 'get_job' is enough to explain a failure – look at 'error_message' and 'steps'. Jobs can nest: when a job has 'has_children' set, pass its ID as parent_id to 'list_jobs' to see the child jobs. Results are newest-first by default. This tool is read-only; it cannot start, retry, pause or abort jobs.

Parameters

Name	Type	Required	Description
operation	string	required	The job operation to perform. Options: 'list_jobs' – list jobs, newest first, with optional filtering by type, status, object, creator or date; 'get_job' – get one job in full, including its steps and error message (requires job_id); 'list_job_history' – like 'list_jobs' but restricted to jobs that have stopped running, i.e. those carrying a completion timestamp. Pass status to narrow to one finished status (FINISHED, FINISHED_WITH_WARNING, FAILED, ABORTED, SKIPPED, DISCARDED); 'get_job_aggregations' – return only the aggregated facet counts rather than the jobs themselves, for questions like 'how many jobs failed, by type'. Use the aggregations parameter to choose which fields to group by.
job_id	string	optional	UUID of the job (required for 'get_job').
status	string	optional	Filter by job status. One of: READY, STARTED, FINISHED, FINISHED_WITH_WARNING, FAILED, WAITING, ABORT_PENDING, ABORTED, SKIPPED, PAUSED, PENDING_USER, DISCARDED. For 'list_job_history' this narrows the history to a single status and must be one of the finished statuses.
job_type	string	optional	Filter by job type, e.g. 'TRANSCODE', 'ANALYZE', 'TRANSFER', 'SCAN', 'EXPORT'. Use 'get_job_aggregations' with aggregations='type' to discover which types exist on this system.
object_type	string	optional	Filter by the type of object the job acted on, e.g. 'assets', 'collections', 'storages'.
object_id	string	optional	Filter by the UUID of the object the job acted on. Combine with object_type to answer 'what has happened to this asset?'.
parent_id	string	optional	Filter to the child jobs of this parent job UUID. Use this to expand a job whose 'has_children' field is true.
created_by	string	optional	Filter by the UUID of the user who created the job.
automation_id	string	optional	Filter to the jobs created by a specific automation.
date_created	string	optional	Filter by creation date. A single ISO8601 timestamp, or two separated by a semicolon to express a range, where either side may be '' to leave the range open ended. Example: '2024-01-01T10:00:00Z;2024-01-01T15:00:00Z' or '2024-01-01T00:00:00Z;'.
date_modified	string	optional	Filter by modification date, in the same format as date_created.
ids	string	optional	Comma-separated list of job UUIDs to fetch.
query	string	optional	Free-text filter across the above fields, with wildcard support.
exists	string	optional	Comma-separated list of field names; only jobs that have all of these fields are returned. Example: 'error_message' to find jobs that recorded an error.
missing	string	optional	Comma-separated list of field names; only jobs missing all of these fields are returned.
aggregations	string	optional	For 'get_job_aggregations': comma-separated list of fields to group the counts by, e.g. 'status', 'type', or 'status,type'. Defaults to 'status'.
sort	string	optional	Comma-separated field name and direction, e.g. 'date_created,desc'. Defaults to 'date_created,desc' so the newest jobs come first.
page	integer	optional	Page number for pagination (default: 1).
per_page	integer	optional	Number of results per page (max 100, default 10).

query_iconik_metadata Metadata Query Iconik metadata views, fields, and individual asset metadata.

Query Iconik metadata views, fields, and individual asset metadata. Provides comprehensive access to Iconik's metadata system: list available metadata views and their fields, get details about specific metadata fields, retrieve metadata values for specific assets or objects, and explore the metadata schema to understand what fields are available for search. IMPORTANT: Use this tool to discover field names for search queries! Field names found here should be used with 'metadata.FieldName:' syntax in search_iconik. Example: if this tool shows a field named 'Photographer', use 'metadata.Photographer: Mike*' in search.

Parameters

Name	Type	Required	Description
operation	string	required	The metadata operation to perform. Options: 'list_views' – get all available metadata views; 'get_view' – get details about a specific view (requires view_id); 'list_fields' – get all available metadata fields; 'get_field' – get details about a specific field (requires field_name); 'get_asset_metadata' – get metadata values for an asset (requires asset_id and view_id); 'get_object_metadata' – get metadata values for any object (requires object_type, object_id, and view_id).
asset_id	string	optional	UUID of the asset (for asset-specific metadata queries).
view_id	string	optional	UUID of the metadata view to query.
field_name	string	optional	Name of the metadata field to get details about.
object_type	string	optional	Type of object (e.g., 'assets', 'collections', 'segments'). Required for 'get_object_metadata'.
object_id	string	optional	UUID of the object to get metadata for.
version_id	string	optional	UUID of the asset version (for asset metadata queries).

query_iconik_saved_searches Saved Searches Query Iconik saved searches and their contents.

Query Iconik saved searches and their contents. Provides access to Iconik's saved search system, allowing you to list all saved searches, get the results of a specific saved search, or get aggregated information about the content of a saved search (asset count, total size, total duration). IMPORTANT: Do NOT mention saved search IDs unless explicitly asked by the user. Format saved search names as clickable links: [Search Name](https://app.iconik.io/search/{search_id}). For 3 or fewer items, display thumbnails using the thumbnail_url from results. Focus on saved search names, descriptions, and relevant metadata in your response.

Parameters

Name	Type	Required	Description
operation	string	required	The saved search operation to perform. Options: 'list_saved_searches' – list all available saved searches; 'get_saved_search_results' – get the search results for a specific saved search (requires search_id); 'get_saved_search_info' – get aggregated information about a saved search's content, including asset/collection counts, total file size, and total duration (requires search_id).
search_id	string	optional	UUID of the saved search (required for search-specific queries).
page	integer	optional	Page number for pagination (default: 1).
per_page	integer	optional	Number of results per page.
include_results	boolean	optional	For 'get_saved_search_results': set to False to return only the search definition without executing the search (default: True).
format_name	string	optional	For 'get_saved_search_info': compute total size only for files with the specified format name (default: 'ORIGINAL').
by_storage_id	boolean	optional	For 'get_saved_search_info': whether to group size results by storage ID (default: True).
query	string	optional	For 'list_saved_searches': filter saved searches by name using a search query string.
favorites	boolean	optional	For 'list_saved_searches': if True, return only favourite saved searches.

query_iconik_settings Settings Query Iconik settings (read-only).

Query Iconik settings (read-only). Iconik settings are layered: system-wide defaults are overridden by group and team settings, which are in turn overridden by a user's own settings. The 'get_merged_settings' operation returns the effective result of that layering, which is what the iconik web app actually applies, so prefer it when answering 'what will happen for this user'. Use the per-layer operations when the question is 'where does this value come from' or 'what has this group overridden'. Note that a 'user' here means a settings override layer, not the user account itself – use the user tools for names, emails, roles and group membership. Typical uses: which features are enabled on the domain, the date/time format, the default upload storage, share expiration and watermark defaults, MFA and password requirements, allowed IPs and CORS hosts, the configured home page and dashboard, and the seat/storage/traffic limits on the domain. Reading your own settings and the system settings needs no extra permission. Reading another user's, a group's or a team's settings requires the corresponding permission and returns a clear error when you do not have it. This tool is read-only; it cannot change any setting.

Parameters

Name	Type	Required	Description
operation	string	required	The settings operation to perform. Options: 'get_system_settings' – the system-wide settings for the domain, i.e. the defaults everything else overrides (no extra permission needed for your own domain); 'get_merged_settings' – the effective settings after system, group, team and user layers have been merged; defaults to the authenticated user, or pass user_id for someone else; 'get_user_settings' – only the overrides set on a user, defaulting to the authenticated user; 'get_group_settings' – only the overrides set on a group (requires group_id); 'get_team_settings' – only the overrides set on a team (requires team_id); 'list_cors_hosts' – the CORS hosts allowed to call the API for this domain; 'get_cors_host' – one CORS host (requires cors_host_id); 'get_search_view_groups' – the IDs of the groups that use a given search view, which is how you audit search-view assignment (requires view_id).
user_id	any	optional
group_id	any	optional
team_id	any	optional
system_domain_id	any	optional
cors_host_id	any	optional
view_id	any	optional
ignore_logo_url	any	optional

query_iconik_storages Storages Query Iconik storages (read-only).

Query Iconik storages (read-only). Provides access to Iconik's storage system: list the storages configured on the system, get the details of a specific storage, find the storages that match a given purpose, resolve the default storage for a purpose, and list the files held on a storage. Use this to answer questions about where media lives, which storages are active or failing, when a storage was last scanned, and what is stored on it. Storage methods: FILE, HTTP, FTP, SFTP, S3, B2, GCS, PORTAL, CUSTOM, AZURE. Storage purposes: KEYFRAMES, FILES, PROXIES, EXPORTS, ARCHIVE, FACES. Storage statuses: ACTIVE, INACTIVE, FAILING. Any credential fields in a storage's settings are redacted before being returned. IMPORTANT: Do NOT mention storage IDs unless explicitly asked by the user – refer to storages by name. This tool is read-only; it cannot create, update or delete storages.

Parameters

Name	Type	Required	Description
operation	string	required	The storage operation to perform. Options: 'list_storages' – list the storages configured on the system, with optional filtering by name, method, status, purpose or scanner status; 'get_storage' – get the full details of one storage (requires storage_id); 'get_matching_storages' – find the storages that can serve a given purpose, optionally narrowed to a single method (requires purpose); 'get_default_storage' – get the default storage for a purpose (requires purpose); 'list_storage_files' – list the files held on a storage, optionally filtered by path or directory (requires storage_id).
storage_id	any	optional
purpose	any	optional
method	any	optional
status	any	optional
name	any	optional
scanner_status	any	optional
last_scanned	any	optional
ids	any	optional
path	any	optional
directory_path	any	optional
path_separator	any	optional
checksum	any	optional
file_type	any	optional
date_created	any	optional
date_modified	any	optional
query	any	optional
sort	any	optional
page	integer	optional	Page number for pagination (default: 1).
per_page	any	optional

query_iconik_users Users Query full Iconik user, group, team and role-group objects (read-only).

Query full Iconik user, group, team and role-group objects (read-only). Use this when the lightweight get_users_basic / get_groups_basic tools do not carry enough detail – for example to see a user's status, admin flag, group membership, primary group or last login, or to see which roles a group grants. Every authenticated user can read their own record and roles via 'get_current_user_detail' and 'get_current_user_roles'. Reading other users, groups, teams or role groups requires the corresponding permission, and returns a clear error when the user does not have it. IMPORTANT: Do NOT mention user or group IDs unless explicitly asked by the user – refer to people by name and groups by their name. Treat email addresses and phone numbers as personal data: include them only when the user's request actually calls for them. This tool is read-only; it cannot create, update or delete users or groups.

Parameters

Name	Type	Required	Description
operation	string	required	The operation to perform. Options: 'get_current_user_detail' – the full record of the authenticated user (no extra permission needed); 'get_current_user_roles' – the roles held by the authenticated user (no extra permission needed); 'list_users' – list full user objects, with optional filtering; 'get_user' – one full user object (requires user_id); 'get_user_roles' – the roles held by a specific user (requires user_id); 'list_groups' – list groups; 'get_group' – one group in full (requires group_id); 'list_teams' – list teams; 'get_team' – one team in full (requires group_id); 'list_role_groups' – list role groups; 'get_role_group' – one role group in full (requires group_id).
user_id	any	optional
group_id	any	optional
query	any	optional
ids	any	optional
name	any	optional
alias	any	optional
first_name	any	optional
last_name	any	optional
email	any	optional
status	any	optional
is_admin	any	optional
groups	any	optional
roles	any	optional
date_created	any	optional
date_modified	any	optional
sort	any	optional
page	integer	optional	Page number for pagination (default: 1).
per_page	any	optional

search_iconik Search Search for assets and collections in Iconik using advanced query syntax.

Search for assets and collections in Iconik using advanced query syntax. IMPORTANT: When returning search results to users: do NOT mention asset IDs unless explicitly asked by the user; format asset titles as clickable links: [Asset Title](https://app.iconik.io/asset/{asset_id}). for 3 or fewer assets, display thumbnails using the thumbnail_url from search results; focus on asset titles, descriptions, and relevant metadata in your response. SEARCH SYNTAX: (1) Metadata fields: use 'metadata.FieldName:' prefix, e.g. 'metadata.Photographer: Mike*', 'metadata.Category: Cars', 'metadata.Keywords: vacation'. (2) System fields: use field name directly, e.g. 'title:"BMW"', '_exists_:transcription_text', 'date_created:[2023-01-01 TO 2023-12-31]'. (3) Wildcards: * for multiple chars, ? for single char, e.g. 'title:water*'. (4) Boolean: AND, OR, NOT, e.g. 'metadata.Category: Cars AND metadata.Photographer: Mike*'. (5) Exact phrases: use quotes, e.g. 'title:"BMW X5 Review"'. (6) Ranges: 'metadata.startdate:[2018-06-06 TO 2018-06-12]', 'metadata.age:[40 TO 50]'. (7) Transcription search: use the filter parameter with transcription_text. (8) Discover fields: use query_iconik_metadata tool to list available views and fields.

Parameters

Name	Type	Required	Description
query	string	required	Search query string. Use 'metadata.FieldName:' for custom metadata fields. Examples: 'metadata.Photographer: Mike' (finds photographers named Mike); 'metadata.Category: Cars AND metadata.Keywords: BMW'; 'title:"BMW X5"' (searches asset titles); 'date_created:[2023-01-01 TO 2023-12-31]' (date range); '"exact phrase"' (exact phrase search); 'title:water' (finds water, Waterloo, waterskis); 'metadata.status:approved OR metadata.status:pending'; 'metadata.first_name:Barack AND NOT metadata.last_name:Obama'. Use the filter parameter for transcription searches.
doc_types	array	optional	Types of documents to search (e.g., ['assets', 'collections']).
page	integer	optional	Page number for pagination (default: 1).
per_page	integer	optional	Number of results per page. (Default: 10)
save_search_history	boolean	optional	Whether to save this search in history.
generate_signed_url	boolean	optional	Whether to generate signed URLs for results.
generate_signed_download_url	boolean	optional	Whether to generate signed download URLs.
generate_signed_proxy_url	boolean	optional	Whether to generate signed proxy URLs.
sort	array	optional	Sort criteria. Example: [{"field": "date_created", "order": "desc"}]
facets	array	optional	Facet fields to include in results.
filter	object	optional	Advanced filter criteria for complex searches. Use this for transcription searches. Example: {"operator": "AND", "terms": [{"name": "transcription_text", "value": "fortnite"}, {"name": "status", "value_in": ["ACTIVE"]}]}
fields	array \| string	optional	Fields to include in each result object. Pass a list of field names to restrict the response to those fields. Pass "ALL" to return every available field. Omit (or pass null) to use the default set: title, date_created, created_by_user, duration, media_type, metadata, type, format, id.

update_iconik_asset Assets Update properties of an Iconik asset.

Update properties of an Iconik asset. Use this to modify asset titles or other technical asset information. Metadata is managed separately using the metadata tool.

Parameters

Name	Type	Required	Description
asset_id	string	required	UUID of the asset to update.
patch_data	object	required	Dictionary containing the fields to update. Common fields include 'title' (new title for the asset).

update_iconik_metadata Metadata Update Iconik metadata fields.

Update Iconik metadata fields. IMPORTANT: make sure to wrap the metadata in '{"metadata_values": {}}'. The schema for metadata_values is: { "metadata_values": { "string_field_name": { "field_values": [{"value": "New Value"}] }, "tag_field_name": { "field_values": [{"value": "Tag 1"}, {"value": "Tag 2"}] }, "date_field_name": { "field_values": [{"value": "2026-03-01T00:00:00Z"}] } } }

Parameters

Name	Type	Required	Description
view_id	string	required	UUID of the metadata view to update. If the user is admin, this can be set to None and any field can be updated directly.
object_type	string	required	Type of object (e.g., 'assets', 'collections', 'segments').
object_id	string	required	UUID of the object whose metadata should be updated.
metadata_values	object	required	The metadata values to set, keyed by field name, wrapped in '{"metadata_values": {}}'.
version_id	string	optional	UUID of the asset version (only relevant when object_type is 'assets'). If not specified the latest version is used.

Connect AI agents to your media library

General Setup Instructions

Claude

Claude Desktop

Claude Code

Visual Studio Code

Cursor

Zed

Other clients

Native HTTP transport (preferred)

stdio via mcp-remote bridge

Available tools