MCP Server Tools

Released & Rapidly Expanding

Aprimo's MCP Server is released and available. This article documents the tools available today, and we are rapidly expanding the set — check back often to discover new tools we are supporting. If you have a use case you would like covered by the Aprimo MCP Server, reach out to your Aprimo Customer Success Manager.

Aprimo's MCP Server exposes DAM capabilities as callable tools that LLMs can discover and invoke dynamically. These tools are designed for use in chat-based agents and autonomous pipelines where the LLM decides when and how to retrieve or update content in Aprimo.

For guidance on when to use MCP tools versus the REST API, see REST API vs. MCP.

Configuration

License Requirement

The MCP Server requires an AI Elite license. Client registration for MCP is available by default for all customers with AI Elite. If your organization does not currently have AI Elite and procures it in the future, Aprimo will enable the feature for you.

Create a Client Registration

Before connecting an MCP client, create a registration in your Aprimo tenant:

Go to Administration > Integration > Registrations.
Create a new registration with the following values:

Field	Value
Client	`mcp_client`
OAuth Flow Type	Model Context Protocol (MCP)
Redirect URL	The redirect URL provided by your MCP client

Once saved, Aprimo generates a Client ID. Use this Client ID when configuring your MCP client (such as Copilot Studio or VS Code with an MCP extension) to connect to the server.

Connection Details

Use the following URLs when configuring your MCP client. Replace [aprimoEnvironment] with your Aprimo environment name.

Setting	URL
Server URL	`https://[aprimoEnvironment].aprimo.com/mcp`
Authorization URL	`https://[aprimoEnvironment].aprimo.com/login/connect/authorize`
Token URL	`https://[aprimoEnvironment].aprimo.com/login/connect/token`
Refresh URL	`https://[aprimoEnvironment].aprimo.com/login/connect/token`
Scope	`mcp`

The mcp scope grants access to all MCP tools.

Tools at a Glance

DAM Tools

Tool	What It Does
`search_aprimo`	Search Aprimo and return matching records with metadata
`get_record_metadata`	Return base fields, file info, and custom fields for a specific record
`get_record_thumbnail_url`	Return the thumbnail URL for the latest version of a record
`get_record_preview_url`	Return the preview URL for the latest version of a record
`get_record_download_url`	Place a download order and return the download URL
`update_record_metadata_field`	Update a metadata field on a record
`get_custom_field_definition`	Return the definition and available values for a custom field

Productivity Management Tools

Tool	What It Does
`search_activities`	Search Activities (campaigns) in Aprimo Productivity Management and return a paged list with resolved labels
`search_projects`	Search Projects in Aprimo Productivity Management and return a paged list with resolved labels

search_aprimo

Executes a keyword search against Aprimo under the context of the authenticated user and returns matching records.

Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	Core search terms only — no filler text or conversational phrasing
`limit`	integer	No	Maximum results to return (1–50, default 20)
`offset`	integer	No	Results to skip for pagination (default 0)
`sort`	string	No	Sort order: `relevance` (default), `modified_desc`, `modified_asc`, `created_desc`, `created_asc`, `title_asc`, `title_desc`, `popularity`
`createdAfter`	string	No	ISO 8601 date — filter to records created on or after this date
`createdBefore`	string	No	ISO 8601 date — filter to records created on or before this date
`modifiedAfter`	string	No	ISO 8601 date — filter to records modified on or after this date
`modifiedBefore`	string	No	ISO 8601 date — filter to records modified on or before this date
`fileType`	string	No	Filter by file extension (e.g., `jpg`, `pdf`, `mp4`)

Returns:

{
  "total_count": 142,
  "count": 20,
  "offset": 0,
  "has_more": true,
  "next_offset": 20,
  "searchResultsLink": "https://[tenant].dam.aprimo.com/...",
  "items": [
    {
      "title": "Product Hero Image",
      "deepLink": "https://[tenant].dam.aprimo.com/dam/contentitems/abc123",
      "contentType": "image/jpeg",
      "fileExtension": "jpg",
      "createdDate": "January 15, 2025",
      "modifiedDate": "March 22, 2025",
      "previewUri": "https://...",
      "customFields": [...]
    }
  ]
}

The searchResultsLink is a direct link to the full results page in Aprimo. Use has_more and next_offset to page through results.

get_record_metadata

Returns the full metadata for a specific record — base system fields, master file information, and all custom fields with their localized values.

Parameters:

Parameter	Type	Required	Description
`recordId`	string (GUID)	Yes	The Aprimo record ID — obtain from `search_aprimo` results

Returns:

{
  "id": "a1b2c3d4-...",
  "title": "Product Hero Image",
  "status": "released",
  "contentType": "image/jpeg",
  "createdOn": "2025-01-15T09:00:00Z",
  "modifiedOn": "2025-03-22T14:30:00Z",
  "deepLink": "https://[tenant].dam.aprimo.com/dam/contentitems/a1b2c3d4-...",
  "masterFile": {
    "fileName": "hero-image.jpg",
    "extension": "jpg",
    "fileSize": 4823041,
    "versionNumber": 3
  },
  "fields": [
    {
      "id": "field-def-guid",
      "fieldName": "productCategory",
      "label": "Product Category",
      "dataType": "OptionList",
      "localizedValues": [
        {
          "languageId": "lang-guid",
          "value": null,
          "values": ["Cameras"]
        }
      ]
    }
  ]
}

Each field in the fields array contains its definition ID (used to call get_custom_field_definition) and localizedValues — one entry per language the field supports. The languageId from this response is required when calling update_record_metadata_field.

get_record_thumbnail_url

Returns the thumbnail URL for the latest version of a record. Thumbnails are small images (typically 150×150 pixels) suited for list and grid displays.

Parameters:

Parameter	Type	Required	Description
`recordId`	string (GUID)	Yes	The Aprimo record ID — obtain from `search_aprimo` results

Returns:

{
  "id": "a1b2c3d4-...",
  "title": "Product Hero Image",
  "uri": "https://...",
  "width": 150,
  "height": 150,
  "extension": "jpg"
}

The uri contains a time-limited SAS token (typically valid for 24 hours). If no thumbnail exists for the record, the tool returns a descriptive message rather than an error.

get_record_preview_url

Returns the preview URL for the latest version of a record. Previews are larger (typically 800×600 pixels) and support a broader range of file types than thumbnails.

Parameters:

Parameter	Type	Required	Description
`recordId`	string (GUID)	Yes	The Aprimo record ID — obtain from `search_aprimo` results

Returns:

{
  "id": "a1b2c3d4-...",
  "title": "Product Hero Image",
  "uri": "https://...",
  "width": 800,
  "height": 600,
  "extension": "jpg"
}

The uri contains a time-limited SAS token (typically valid for 24 hours). If no preview exists for the record, the tool returns a descriptive message rather than an error.

get_record_download_url

Places a download order for a record and returns a URL to download the original file. Use this when an agent needs access to the actual file — for example, to pass an asset to an external model for analysis or metadata enrichment.

Parameters:

Parameter	Type	Required	Description
`recordId`	string (GUID)	Yes	The Aprimo record ID — obtain from `search_aprimo` or `get_record_metadata`

Returns:

{
  "downloadUrl": "https://...",
  "orderId": "order-guid",
  "totalFileSize": 4823041
}

The tool places a download order via the Aprimo Orders API and polls for completion before returning. The downloadUrl contains a time-limited SAS token.

Behavior to be aware of

Not idempotent — each call creates a new download order in Aprimo.
No transformations — the download URL returns the original master file only. Crops, renditions, and format conversions are not currently supported.
SAS token is time-limited — do not cache the URL for later use; call the tool again when a fresh download is needed.

update_record_metadata_field

Updates the value of a single metadata field on a record.

Parameters:

Parameter	Type	Required	Description
`recordId`	string (GUID)	Yes	The Aprimo record ID
`languageId`	string (GUID)	Yes	The language ID — obtain from `get_record_metadata` results (`fields[].localizedValues[].languageId`)
`fieldName`	string	One of `fieldName` or `fieldId`	The field name to update
`fieldId`	string (GUID)	One of `fieldName` or `fieldId`	The field definition ID to update — obtain from `get_record_metadata` results (`fields[].id`)
`value`	string	No	New value for single-value fields (text, number, date). Dates use ISO 8601; numbers pass as string
`values`	string[]	No	New values for multi-value fields (text-list, option list). For option lists, use option names from `get_custom_field_definition`
`clear`	boolean	No	Set to `true` to clear the field value (default `false`)

Returns:

{
  "recordId": "a1b2c3d4-...",
  "fieldName": "productCategory",
  "success": true,
  "message": null
}

Supported field types at launch:

Field Type	Use `value` or `values`?
Single-line text	`value`
Multi-line text	`value`
Numeric	`value` (pass number as string)
Date / DateTime	`value` (ISO 8601 format)
Text list	`values`
Option list	`values` (use option names from `get_custom_field_definition`)
Classification list	`values` (use option names from `get_custom_field_definition`)

For option list and classification list fields, call get_custom_field_definition first to retrieve the valid option names, then pass them in values.

Write Operations Are Real

Changes made through this tool are applied to your live Aprimo tenant and appear in the audit log. Test in a non-production environment before running automated pipelines.

get_custom_field_definition

Returns the full definition of a custom field — including its data type, validation rules, and for option list and classification fields, the complete set of valid values.

Parameters:

Parameter	Type	Required	Description
`fieldDefinitionId`	string (GUID)	Yes	The field definition ID — obtain from `get_record_metadata` results (`fields[].id`)

Returns:

{
  "id": "field-def-guid",
  "name": "productCategory",
  "label": "Product Category",
  "dataType": "OptionList",
  "isRequired": false,
  "isReadOnly": false,
  "acceptMultipleOptions": false,
  "helpText": "Select the primary product category for this asset.",
  "items": [
    { "id": "opt-1", "name": "cameras",     "label": "Cameras" },
    { "id": "opt-2", "name": "monitors",    "label": "Monitors" },
    { "id": "opt-3", "name": "televisions", "label": "Televisions" }
  ]
}

The items array is present for OptionList and ClassificationList fields and contains all valid values. Use the name property from each item when calling update_record_metadata_field. The acceptMultipleOptions flag tells you whether the field accepts one or many values.

search_activities

Searches Activities (marketing campaigns) in Aprimo Productivity Management and returns a paged list with resolved labels for activity type, state, time zone, owner, and administrator.

Tenant Terminology

Aprimo allows tenants to rename the Activity object (e.g. to "Plan", "Campaign", or "Initiative"). This tool recognizes whatever term the user says and maps it to the underlying Activity object automatically.

Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	JSON-encoded search filter using PM's operator-tree DSL. Pass `{}` to match all activities. See Query DSL below
`limit`	integer	No	Maximum results to return (1–50, default 20)
`offset`	integer	No	Results to skip for pagination (default 0)
`sortField`	string	No	Field name to sort by (e.g. `ModifiedDate`, `Name`). Omit for default ordering
`sortAscending`	boolean	No	Sort direction — `true` for ascending (default), `false` for descending
`activityTypeLabel`	string	No	Filter by activity type label (case-insensitive, e.g. `Initiative`). Returns an error if the label doesn't match a known type
`activityStateLabel`	string	No	Filter by activity state label (case-insensitive, e.g. `Active`). Returns an error if the label doesn't match a known state
`ownerName`	string	No	Filter by owner's first or last name (case-insensitive substring). Returns an empty result set if no users match
`administratorName`	string	No	Filter by administrator's first or last name (case-insensitive substring). Returns an empty result set if no users match
`attributeFilters`	object	No	Filter by extended attribute value. Keys are the attribute's display name (e.g. `Phase Gate`), values are the target value as a string
`attributesPresent`	object	No	Filter by extended attribute presence. Keys are the attribute's display name, values are `true` (has any value) or `false` (has no value)

Returns:

{
  "totalRecords": 84,
  "count": 20,
  "offset": 0,
  "hasMore": true,
  "nextOffset": 20,
  "items": [
    {
      "activityId": 13801,
      "title": "Q3 Product Launch",
      "description": "Global launch campaign for the Q3 product line.",
      "activityTypeLabel": "Initiative",
      "activityStateLabel": "Active",
      "timeZoneLabel": "Eastern Time (US & Canada)",
      "beginDate": "January 6, 2026",
      "endDate": "September 30, 2026",
      "projectAnchorDate": "October 15, 2026",
      "ownerName": "Alice Adams",
      "administratorName": "Bob Chen",
      "deepLink": "https://[tenant].aprimo.com/MarketingOps/#/mo?PageID=2200&ID=13801&Mode=2"
    }
  ]
}

Important date fields:

Field	Wire name	What it represents
`endDate`	`VisualEndDate`	The user-facing End Date shown in the UI
`projectAnchorDate`	`EndDate`	The Project Anchor Date (confusingly named on the wire)

When filtering by date in the query DSL, use VisualEndDate for the end date and EndDate for the project anchor date.

search_projects

Searches Projects in Aprimo Productivity Management and returns a paged list with resolved labels for status, project manager, and the linked Activity.

Tenant Terminology

Aprimo allows tenants to rename the Project object (e.g. to "Workstream", "Effort", or "Track"). This tool recognizes whatever term the user says and maps it to the underlying Project object automatically.

Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	JSON-encoded search filter using PM's operator-tree DSL. Pass `{}` to match all projects. See Query DSL below
`limit`	integer	No	Maximum results to return (1–50, default 20)
`offset`	integer	No	Results to skip for pagination (default 0)
`sortField`	string	No	Field name to sort by (e.g. `ModifiedDate`, `Title`). Omit for default ordering
`sortAscending`	boolean	No	Sort direction — `true` for ascending (default), `false` for descending
`projectStatusLabel`	string	No	Filter by project status label (case-insensitive, e.g. `Active`, `Closed`). Returns an error if the label doesn't match a known status
`projectManagerName`	string	No	Filter by project manager's first or last name (case-insensitive substring). Returns an empty result set if no users match
`attributeFilters`	object	No	Filter by extended attribute value. Keys are the attribute's display name, values are the target value as a string
`attributesPresent`	object	No	Filter by extended attribute presence. Keys are the attribute's display name, values are `true` (has any value) or `false` (has no value)

Returns:

{
  "totalRecords": 12,
  "count": 12,
  "offset": 0,
  "hasMore": false,
  "nextOffset": null,
  "items": [
    {
      "projectId": 67890,
      "title": "Website Hero Assets",
      "projectStatusLabel": "Active",
      "description": "Produce all hero images for the Q3 campaign landing pages.",
      "beginDate": "February 1, 2026",
      "endDate": "August 31, 2026",
      "projectManagerName": "Alice Adams",
      "activityId": 13801,
      "activityName": "Q3 Product Launch",
      "activityDeepLink": "https://[tenant].aprimo.com/MarketingOps/#/mo?PageID=2200&ID=13801&Mode=2",
      "deepLink": "https://[tenant].aprimo.com/MarketingOps/#/project-overview?projectId=67890"
    }
  ]
}

Date fields are UTC

beginDate and endDate on projects are returned in UTC. This differs from Activity dates, which are returned in the activity's configured time zone.

PM Query DSL

Both search_activities and search_projects accept a query parameter that uses PM's operator-tree DSL — a JSON object with a single top-level operator. This is not a flat key-value object.

Available operators (all lowercase):

Type	Operators
Comparison	`equals`, `contains`, `lessthan`, `lessthanorequalto`, `greaterthan`, `greaterthanorequalto`, `isnull`, `isnotnull`
Logical	`and`, `or`, `not`

Leaf operators take FieldName and FieldValue in PascalCase. Logical operators (and, or) take an array of operations; not takes a single operation object.

Examples:

// Match all
{}

// By name (partial match)
{"contains": {"FieldName": "Name", "FieldValue": "launch"}}

// By activity ID
{"equals": {"FieldName": "ActivityId", "FieldValue": 13801}}

// By project end date (before July 1)
{"lessthan": {"FieldName": "EndDate", "FieldValue": "2026-07-01"}}

// Compound: active campaigns named "Q4"
{"and": [
  {"equals": {"FieldName": "ActivityStateId", "FieldValue": 1}},
  {"contains": {"FieldName": "Name", "FieldValue": "Q4"}}
]}

For status, type, owner, and manager filtering, prefer the named filter parameters (activityTypeLabel, projectStatusLabel, etc.) over composing the DSL — they resolve display labels to IDs automatically and are less error-prone.

Typical Tool Chains

These tools are designed to work together. Two common sequences:

Read and enrich a record:

search_aprimo (find the record)
  → get_record_metadata (inspect field names, IDs, and language IDs)
  → get_custom_field_definition (get valid option values for the field)
  → update_record_metadata_field (write the new value)

Fetch content for external processing:

search_aprimo (find the record)
  → get_record_download_url (get the original file)
  → [external model processes the file]
  → update_record_metadata_field (write back derived metadata)

Authentication

All MCP tools execute under the context of the authenticated user. Authorization is enforced per-user — if a user does not have permission to view or edit a record in Aprimo, the corresponding tool call will respect that restriction.

Aprimo's MCP Server uses OAuth 2.0 with the Authorization Code + PKCE flow. See the OAuth2 documentation for setup details.

The Invocation Pattern — when and how to call Aprimo from an orchestration platform via MCP or REST
REST API vs. MCP — choosing the right integration approach for your agent
DAM REST API — REST API reference for pre-orchestrated workflows

Configuration​

License Requirement​

Create a Client Registration​

Connection Details​

Tools at a Glance​

search_aprimo​

get_record_metadata​

get_record_thumbnail_url​

get_record_preview_url​

get_record_download_url​

update_record_metadata_field​

get_custom_field_definition​

search_activities​

search_projects​

PM Query DSL​

Typical Tool Chains​

Authentication​

Related​

Configuration

License Requirement

Create a Client Registration

Connection Details

Tools at a Glance

search_aprimo

get_record_metadata

get_record_thumbnail_url

get_record_preview_url

get_record_download_url

update_record_metadata_field

get_custom_field_definition

search_activities

search_projects

PM Query DSL

Typical Tool Chains

Authentication

Related