Iconik MCP Server – Setup & Documentation

General Setup Instructions

The Iconik MCP server uses Bearer token authentication. Every client configuration passes your Iconik API token via an Authorization: Bearer <token> header. All clients except Zed use the mcp-remote npx bridge to forward this header to the server.

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

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

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_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_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 General 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.

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