Search for assets using standard filters or semantic search.
Assets must be uploaded through the Metabind interface before they can be referenced in content. The MCP tools provide discovery and search capabilities, not upload functionality.
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Project ID (optional, uses session default if not provided)"
},
"query": {
"type": "string",
"description": "Natural language query for semantic search. When provided, results are ranked by relevance."
},
"type": {
"type": "string",
"description": "Filter by MIME type or category (image/*, video/*, etc.)"
},
"tags": {
"type": "array",
"items": { "type": "string" },
"description": "Filter by tags. Accepts tag names or IDs."
},
"page": {
"type": "number",
"default": 1,
"description": "Page number for paginated results (1-based indexing)"
},
"limit": {
"type": "number",
"default": 20,
"maximum": 100,
"description": "Maximum items to return per page"
}
}
}
Parameters
| Parameter | Type | Default | Description |
|---|
projectId | string | session default | Project to search in |
query | string | - | Natural language semantic search query |
type | string | - | Filter by MIME type (e.g., image/jpeg, image/*) |
tags | string[] | - | Filter by tags |
page | number | 1 | Page number |
limit | number | 20 | Items per page (max 100) |
Response
| Field | Type | Description |
|---|
items | array | Array of asset objects |
items[].id | string | Unique asset identifier |
items[].name | string | Display name for the asset |
items[].description | string | Asset description or metadata |
items[].type | string | MIME type of the asset |
items[].url | string | CDN URL for accessing the asset |
items[].dimensions | object | Asset dimensions (for images/videos) |
items[].dimensions.width | number | Width in pixels |
items[].dimensions.height | number | Height in pixels |
items[].size | number | File size in bytes |
items[].tags | string[] | Categorization tags |
items[].similarity | number | Similarity score 0-1 (when query is used) |
total | number | Total number of matching items |
Examples
Semantic Search
Search for assets using natural language:
{
"query": "team collaboration workspace"
}
{
"items": [
{
"id": "asset-workspace-001",
"name": "Workspace Collaboration",
"description": "The Acme design team collaborating on the new unified component library at their San Francisco headquarters.",
"type": "image/jpeg",
"url": "https://cdn.metabind.ai/org123/proj123/assets/workspace-collaboration.jpg",
"dimensions": {
"width": 2048,
"height": 1366
},
"size": 524288,
"tags": ["team", "collaboration", "design-system"],
"similarity": 0.95
}
],
"total": 1
}
Filter by Type
Find all JPEG images:
Find assets with specific tags:
{
"tags": ["hero", "banner"]
}
Combined Filters
Search for hero images using semantic search:
{
"query": "professional office environment",
"type": "image/*",
"tags": ["hero"]
}
Common MIME Types
| Type | Description |
|---|
image/jpeg | JPEG images |
image/png | PNG images |
image/gif | GIF images |
image/webp | WebP images |
image/svg+xml | SVG graphics |
video/mp4 | MP4 videos |
video/webm | WebM videos |
application/pdf | PDF documents |
image/* or video/* to match all images or videos respectively.
Using Assets in Content
When creating content, reference assets by their ID:
{
"asset": {
"id": "asset-workspace-001"
}
}
Always verify asset IDs exist before referencing them in content. Use search_assets to find valid asset IDs. Non-existent asset references will cause validation errors during content creation.
