@cloudinary/structured-metadata-mcp MCP Server

Endpoints

Endpoint	Method	Description
/mcp	POST	Streamable HTTP transportRecommended
/sse	GET	SSE transportDeprecated

Server URL

https://structured-metadata.mcp.cloudinary.com/mcp

Configuration

Add this to your MCP client configuration. OAuth is used by default when no headers are provided.

Minimal (OAuth)

{
  "mcpServers": {
    "@cloudinary/structured-metadata-mcp": {
      "url": "https://structured-metadata.mcp.cloudinary.com/mcp"
    }
  }
}

With API Key

{
  "mcpServers": {
    "@cloudinary/structured-metadata-mcp": {
      "url": "https://structured-metadata.mcp.cloudinary.com/mcp",
      "headers": {
        "cloudinary-url": "cloudinary://api_key:api_secret@cloud_name"
      }
    }
  }
}

Authentication

Method	Description
OAuth 2.0	Default. The OAuth flow is initiated automatically when the client connects with no auth headers.
API Key	Pass `cloudinary-url` header, or individual `cloudinary-cloud-name`, `cloudinary-api-key`, `cloudinary-api-secret` headers.

Configuration Headers

Optional headers to customize server behavior. Applied at session creation time.

Header	Description
`cloudinary-region`	API region: `api`, `api-eu`, or `api-ap`
`cloudinary-tools`	Comma-separated list of tools to enable (e.g. `search-assets,list-images`)

Response Headers

API response headers are collected into _meta.headers on each tool result. The debug preset is active by default.

Header	Description
`cloudinary-collect-headers`	Control which response headers are returned. Accepts: `debug` — rate-limit + request ID (default) `ratelimit` — rate-limit headers only `all` — every response header Or a comma-separated list of exact names, `prefix:<value>`, `regex:<pattern>`, and preset names
`cloudinary-embed-headers`	Set to `true` to also include collected headers in the response body as `_headers`, for clients that don't surface `_meta`

Tool result structure

{
  "_meta": {
    "headers": {
      "x-featureratelimit-limit": "5000",
      "x-featureratelimit-remaining": "4998",
      "x-featureratelimit-reset": "Thu, 13 Feb 2026 00:00:00 GMT",
      "x-request-id": "bfeaccc60050594832508590a358a1a4"
    }
  },
  "content": [{ "type": "text", "text": "{...}" }]
}

Available Tools (11)

create-metadata-field list-metadata-fields get-metadata-field update-metadata-field delete-metadata-field update-metadata-datasource-values delete-metadata-datasource-values create-metadata-rule list-metadata-rules update-metadata-rule delete-metadata-rule

destructiveidempotentopenWorldreadOnly

Creates a new structured metadata field in your account

Creates a new metadata field with the specified properties and configuration.

Parameter	Type	Description
`request` required	{ }object	The metadata field definition.
`allow_dynamic_list_values`	◉booleannull	Whether the metadata field allows adding new options to the datasource dynamically.
`alphabetically_sorted`	◉boolean	Whether datasource values are maintained in case-insensitive alphabetical order. When true, values are automatically sorted on insert and update. Default false.
`datasource`	{ }objectnull	The datasource defined for the metadata field.
`default_disabled`	◉booleannull	Whether the field is disabled in the UI by default.
`default_value`	null	The default value of the metadata field.
`external_id`	Abcstring	The external ID of the metadata field.
`label` required	Abcstring	The label of the metadata field.
`mandatory`	◉booleannull	Whether the metadata field is mandatory.
`restrictions`	{ }objectnull	Controls UI visibility and editability of the field. All three keys are always returned; any omitted key on input defaults to false.
`type` required	Abcstring	The type of the metadata field.
`validation`	{ }objectnull	The validation defined for the metadata field.

destructiveidempotentopenWorldreadOnly

Lists all structured metadata fields defined in your Cloudinary product environment

Retrieves a list of all metadata fields in the product environment based on the provided filters.

Parameter	Type	Description
`external_ids`	[ ]array	The external IDs of the metadata fields to retrieve. if not provided, all metadata fields will be returned.

destructiveidempotentopenWorldreadOnly

Retrieves the definition of a specific structured metadata field by its identifier (external_id)

Retrieves detailed information about the specified metadata field.

Parameter	Type	Description
`external_id` required	Abcstring	The external ID of the metadata field.

destructiveidempotentopenWorldreadOnly

Updates the configuration of an existing metadata field

Updates the properties and configuration of the specified metadata field.

Parameter	Type	Description
`external_id` required	Abcstring	The external ID of the metadata field.
`metadata_field` required	{ }object	The updated metadata field definition.
`allow_dynamic_list_values`	◉booleannull	Whether the metadata field allows adding new options to the datasource dynamically.
`alphabetically_sorted`	◉boolean	Whether datasource values are maintained in case-insensitive alphabetical order. When true, values are automatically sorted on insert and update. Default false.
`datasource`	{ }objectnull	The datasource defined for the metadata field.
`default_disabled`	◉booleannull	Whether the field is disabled in the UI by default.
`default_value`	null	The default value of the metadata field.
`external_id`	Abcstring	The external ID of the metadata field.
`label`	Abcstring	The label of the metadata field.
`mandatory`	◉booleannull	Whether the metadata field is mandatory.
`restrictions`	{ }objectnull	Controls UI visibility and editability of the field. All three keys are always returned; any omitted key on input defaults to false.
`type`	Abcstring	The type of the metadata field.
`validation`	{ }objectnull	The validation defined for the metadata field.

destructiveidempotentopenWorldreadOnly

Deletes a structured metadata field definition from your account

Permanently deletes the specified metadata field and all its associated data.

Parameter	Type	Description
`external_id` required	Abcstring	The external ID of the metadata field.

destructiveidempotentopenWorldreadOnly

Updates the allowed values (the datasource) for a specified metadata field

Updates the values in a metadata field's datasource, including adding, modifying, or changing the order of values.

Parameter	Type	Description
`external_id` required	Abcstring	The external ID of the metadata field to update the datasource for.
`update_datasource_request` required	{ }object	The updated datasource values.
`values`	[ ]array

destructiveidempotentopenWorldreadOnly

Removes one or more allowed values from a metadata field's datasource

Removes specific values from a metadata field's datasource by their external IDs.

Parameter	Type	Description
`external_id` required	Abcstring	The external ID of the metadata field to update the datasource for.
`datasource_external_ids_request` required	{ }object	The datasource entry external IDs to delete.
`external_ids` required	[ ]array	The external IDs of the datasource values.

destructiveidempotentopenWorldreadOnly

Creates a new conditional metadata rule

Creates a new metadata rule with the specified properties and configuration.

Parameter	Type	Description
`request` required	{ }object	The metadata rule to create.
`condition` required	{ }object	The condition that triggers this metadata rule. Can be either a logical expression (and/or) or an atomic condition.
`metadata_field_id` required	Abcstring	The ID of the metadata field this rule applies to.
`name` required	Abcstring	A descriptive name for the metadata rule.
`position`	#integer	The position/order of this rule relative to other rules.
`result` required	{ }object	The result/action to apply when the condition is met.
`activate_values`	{ }objectAbcstring	Controls which enum/set options are available for selection.
`apply_value`	{ }object	Specifies a value to apply to the metadata field.
`mode`	Abcstring	Whether to set as default value (default) or append to existing values (append). Default is default.
`value` required	Abcstring#number[ ]array	The value(s) to apply to the metadata field. Can be string, number, or array of strings/numbers depending on the field type.
`enable`	◉boolean	Whether to enable (true) or disable (false) the metadata field when the condition is met.
`set_mandatory`	◉boolean	Whether to make the metadata field required (true) or optional (false).
`state`	Abcstring	The active or inactive state.

destructiveidempotentopenWorldreadOnly

Retrieves a list of all conditional metadata rules defined in your account

Retrieves a list of all metadata rules in the cloud.

Parameter	Type	Description
`request`	{ }object

destructiveidempotentopenWorldreadOnly

Updates an existing conditional metadata rule's definition

Updates the properties and configuration of an existing metadata rule.

Parameter	Type	Description
`external_id` required	Abcstring	The unique identifier of the metadata rule.
`metadata_rule_update` required	{ }object	The updated metadata rule definition.
`condition`	{ }object	The condition that triggers this metadata rule. Can be either a logical expression (and/or) or an atomic condition.
`metadata_field_id`	Abcstring	The ID of the metadata field this rule applies to.
`name`	Abcstring	A descriptive name for the metadata rule.
`position`	#integer	The position/order of this rule relative to other rules.
`result`	{ }object	The result/action to apply when the condition is met.
`activate_values`	{ }objectAbcstring	Controls which enum/set options are available for selection.
`apply_value`	{ }object	Specifies a value to apply to the metadata field.
`mode`	Abcstring	Whether to set as default value (default) or append to existing values (append). Default is default.
`value` required	Abcstring#number[ ]array	The value(s) to apply to the metadata field. Can be string, number, or array of strings/numbers depending on the field type.
`enable`	◉boolean	Whether to enable (true) or disable (false) the metadata field when the condition is met.
`set_mandatory`	◉boolean	Whether to make the metadata field required (true) or optional (false).
`state`	Abcstring	The active or inactive state.

destructiveidempotentopenWorldreadOnly

Deletes a conditional metadata rule by its ID

Permanently deletes a metadata rule.

Parameter	Type	Description
`external_id` required	Abcstring	The unique identifier of the metadata rule.