# MCP Server Tools

:::warning[In Development]
Aprimo's MCP Server is currently in development. This article documents the tools planned for the initial release. Connection details and configuration guidance will be added when the server is available. Reach out to your Aprimo Customer Success Manager to express interest or discuss your use case.
:::

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](./decision-guides/rest-api-vs-mcp.md).

---

## Tools at a Glance

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

---

## 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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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.

:::important[Behavior to be aware of]
- **Not idempotent** — each call creates a new download order in Aprimo.
- **No transformations at launch** — the download URL returns the original master file only. Crops, renditions, and format conversions are not supported in the initial release.
- **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:**

```json
{
  "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`.

:::important[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:**

```json
{
  "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.

---

## 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](https://developers.aprimo.com/docs/OAuth2) for setup details.

---

## Related

- [The Invocation Pattern](./patterns/invocation-pattern.md) — when and how to call Aprimo from an orchestration platform via MCP or REST
- [REST API vs. MCP](./decision-guides/rest-api-vs-mcp.md) — choosing the right integration approach for your agent
- [DAM REST API](../rest-api/dam/dam-intro.md) — REST API reference for pre-orchestrated workflows