Mediagraph MCP
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Mediagraph MCP search for assets tagged nature"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Mediagraph CLI
A single binary that exposes the entire Mediagraph API to AI agents and shells. Ships as both a CLI (mediagraph <tool>) and an MCP server (mediagraph serve) — same code path, same auth, same output shape.
About Mediagraph: a digital asset management (DAM) platform for organizing, sharing, and AI-tagging media at scale. Learn more at www.mediagraph.io.
Built for agent workflows: every tool call returns JSON on stdout, errors on stderr with stable codes, and global flags handle the boring stuff (auth, pagination, retries, dry-runs, polling).
Install
npm install -g @mediagraph/cli # ships the `mediagraph` commandRelated MCP server: mcp-openverse
Authentication
Interactive (developer machines)
mediagraph auth login # opens a browser, completes OAuth, persists tokens
mediagraph auth status # {authenticated, organization, user, token}Tokens are stored encrypted at ~/.mediagraph/tokens.enc and refreshed automatically.
Headless (CI, sandboxes, agents)
Use a Personal Access Token. Set both env vars:
export MEDIAGRAPH_PAT="<token>"
export MEDIAGRAPH_ORGANIZATION_ID="<numeric org id>"
mediagraph auth status # → {authenticated: true, mode: "pat", ...}Generate a PAT in Mediagraph → Profile → Personal Access Tokens, or via mediagraph create_personal_access_token --name "ci".
CLI usage
mediagraph <tool> [flags] # invoke any tool, prints JSON
mediagraph <tool> --help # show flags for a tool
mediagraph list-tools [--brief] # every tool, JSON
mediagraph search-tools "<query>" # ranked keyword search over the registry
mediagraph skills [name|list|all] # focused Markdown recipes for agents
mediagraph skill # full bundled agent onboarding guide
mediagraph sync ... # continuous folder sync (see below)
mediagraph serve # start the MCP server on stdio
mediagraph auth login | logout | statusTool flags
Every tool's flags are derived from its JSON Schema:
# Flag form
mediagraph search_assets --q "tag_text:nature" --per_page 5
mediagraph create_bulk_job --asset_ids 12,34,56 --tag_names sunset --tag_mode add
# Or pass the whole input as JSON
mediagraph search_assets --json '{"q":"tag_text:nature","per_page":5}'Type coercion: numbers, booleans (--flag / --no-flag), arrays (comma-separated, repeated, or JSON), objects (JSON only).
Global flags
These work with any tool:
Flag | Purpose |
| Auto-paginate |
| Cap total rows when paginating (default 10000) |
| Print the HTTP call instead of executing — safe preview for mutations |
| After a |
| Cap |
| Wrap stdout in |
| Trim |
Examples:
# Get all assets matching a query, capped at 500
mediagraph search_assets --q "tag_text:nature" --all --limit 500
# Preview a destructive op
mediagraph delete_asset --id 42 --dry-run
# Block until a bulk job finishes
mediagraph create_bulk_job --asset_ids 1,2,3 --tag_names sunset --tag_mode add --waitOutput contract
stdout — JSON only (always parseable). With
--envelope, wrapped in{ok, tool, data, meta}.stderr — structured error envelope:
{ok: false, code, error, hint?, context?}.exit code —
0success,1runtime/tool/network,2argument parse error,3auth required.
Stable error codes: AUTH_REQUIRED, BAD_ARGS, UNKNOWN_COMMAND, UNKNOWN_TOOL, NOT_FOUND, RUN_LOCKED, NETWORK, RATE_LIMITED, TOOL_ERROR, CONFIG_ERROR, INTERNAL.
The client honors Retry-After on 429/503 (delta-seconds and HTTP-date forms), caps backoff at 60s, and surfaces X-PAT-Disabled as a structured auth error.
Search syntax
The q parameter on search_assets accepts advanced operators:
Form | Example | Meaning |
Term |
| Match across all searchable fields (cross_fields) |
Phrase |
| Both terms in same field, in order |
Exclude |
| Exclude matches |
Combine |
| Boolean ops |
Field |
| Field-scoped |
Wildcard |
|
|
Existence |
| Has any value / has no value |
Group |
| Parenthesized |
Common fields: tag_text, filename.keyword, description, title, ext, creator_text, copyright, city, state, country.
Continuous folder sync
Mirror a remote storage folder to a local directory (or vice versa) and keep them in sync on a schedule. Resilient to crashes and reboots: every run is idempotent, state persists at ~/.mediagraph/sync/<name>/state.json, and in-flight ops are resumed on the next run.
Three modes: download (pull-only — auto-fetch new assets and new data_version_number bumps; metadata-only changes do NOT re-download), upload (push-only — hash + skip unchanged, mirror folder structure), two-way (conflicts land as <file>.conflict-v<N> next to the local file).
mediagraph sync init my-pull --mode download \
--storage-folder-id 42 --local-path ~/Pictures/mediagraph \
--frequency hourly
mediagraph sync run my-pull # one-shot reconciliation; safe to repeat
mediagraph sync install my-pull # registers a launchd job (macOS)
mediagraph sync status my-pull # JSON summary of last runHarness options (the run command is the same in all cases):
OS scheduler (recommended):
mediagraph sync install <name>writes a launchd plist on macOS. Survives reboots, captures logs.Coding-agent loop: in Claude Code,
/loop 1h mediagraph sync run <name>.Long-running watcher:
mediagraph sync watch <name>for low latency without a cron.Manual: just run
mediagraph sync run <name>whenever.
Discovering tools
The CLI ships ~157 tools. Don't load them all — search:
mediagraph skills # focused guide index
mediagraph skills search # asset search and inspection recipes
mediagraph search-tools "rename file" --limit 5
mediagraph search-tools "watermark"
mediagraph create_bulk_job --help # one tool, full schemaTool groups: assets, search & filters, collections / lightboxes / storage folders, tags & taxonomies, tag imports, rights & sharing, custom meta fields, bulk jobs & uploads, rename presets, meta downloads (background CSV export), workflows, comments, notifications, webhooks, admin (user groups, invites, PATs, organization budget).
Use as an MCP server
For Claude Desktop and other MCP clients:
{
"mcpServers": {
"mediagraph": {
"command": "npx",
"args": ["@mediagraph/cli", "serve"]
}
}
}Or one-click: download the latest mediagraph-mcp.mcpb bundle from Releases.
The MCP server exposes the same tools and a few resources:
mediagraph://asset/{id}— asset detailsmediagraph://collection/{id}— collection with assetsmediagraph://lightbox/{id}— lightbox with assetsmediagraph://search?q={query}— search results
It also includes an interactive visual gallery (search_assets_visual) for thumbnail browsing, inline editing, ratings, tagging, and bulk downloads inside Claude Desktop.
Environment
Variable | Default | Purpose |
| — | Personal Access Token (headless auth) |
| — | Organization id (required with PAT) |
|
| API host |
|
| OAuth host |
| (bundled) | OAuth client id (custom apps) |
| — | OAuth client secret (confidential clients) |
|
| Local OAuth callback port |
|
| Override sync state directory |
Agent guides
mediagraph skills prints focused Markdown guides for agents: search, organize, metadata, ingest, bulk jobs/imports, sharing, workflows, and admin. mediagraph skill prints the full bundled SKILL.md onboarding guide.
Security
Tokens encrypted at
~/.mediagraph/tokens.encOAuth uses PKCE for public clients
PAT auth uses HTTP Basic +
OrganizationIdheader (matches Mediagraph server-side path)Access tokens auto-refreshed before expiration
No secrets logged or exposed in errors
Development
git clone https://github.com/mediagraph-io/mediagraph-mcp.git
cd mediagraph-mcp
npm install
npm run build # tsup bundle to dist/
npm test # vitest, ~110 tests
npm run typecheckRun the local build:
node dist/index.js auth status
node dist/index.js search_assets --q "test" --per_page 5Test with the MCP inspector:
npx @modelcontextprotocol/inspector node dist/index.js serveLicense
MIT — see LICENSE.
Support
Mediagraph — product info, pricing, demos
History provenance
The MCP server automatically sends X-Mediagraph-Source: mcp; CLI commands,
including sync/watch, send X-Mediagraph-Source: cli on authenticated Mediagraph
API requests. The header is not sent to S3 or file-download hosts. Both sources
appear as Agent in Mediagraph History, while remaining separately filterable.
Use get_asset_event_log with request_source set to mcp, cli, web,
api, system, agent (MCP and CLI), or unknown (historical or unattributed records).
Source labels describe provenance, not authorization or human approval.
Dedicated super-admin folder duplication
Preview is the default. An active issuing membership, current super-admin role,
and explicit bulk_job:write or bulk_jobs:write token scope are required.
mediagraph duplicate_storage_folder_to_collection --source 123 --destination 456 --preview
mediagraph duplicate_storage_folder_to_collection --source 123 --destination 456 --execute --idempotency_key request_20261102_example --wait
mediagraph watch bulk_job <guid>
mediagraph cancel_bulk_job --id <guid>The server reports resolved targets, live subtree counts, destination conflicts,
and dedicated worker readiness. It never deletes destination content. Production
needs one separately provisioned admin worker; this command does not provision or
scale it. Occupied capacity returns 409; absent/misconfigured workers return 503.
Reuse the same key after an uncertain response: retries return the existing job.
--dry-run only prints the HTTP request; --preview queries server readiness.
--wait requires execute and follows retries until processed, failed, or canceled.
Inspect the returned error and counts: processed can include a graceful failure.
Do not move/delete source content during a live-tree duplication.
Available Tools
277 toolsaccept_inviteA
Accept an invite using its email-link token (public flow — distinct from accept_my_invite which uses the profile-scoped invite list for an authenticated user).
Inputs: token (required).
accept_my_inviteB
Accept a pending org invitation by id.
Inputs: id (required).
add_assets_to_groupA
Add multiple assets to a Collection or Lightbox at once
Inputs: ids (required), asset_group_id (required).
add_assets_to_uploadB
Add assets to an upload session
Inputs: guid (required), asset_ids (required).
add_asset_to_collectionC
Add an asset to a collection
Inputs: asset_id (required), collection_id (required).
add_asset_to_lightboxB
Add an asset to a lightbox
Inputs: asset_id (required), lightbox_id (required).
add_asset_versionA
Initiate an upload of a NEW version of an existing asset. Returns a signed S3 URL; PUT the file there to complete. For end-to-end uploads from disk, prefer upload_file with the asset id.
Inputs: id (required), filename (required), file_size (required), content_type (required).
add_organization_cai_budgetB
Super-admin: send a Stripe invoice for a CAI budget top-up
Inputs: id (required), amount, description.
add_tags_to_assetC
Add tags to an asset
Inputs: id (required), tags (required).
add_tag_to_taxonomyB
Add an existing tag to a taxonomy as a taxonomy_tag.
Inputs: id (required), taxonomy_id (required).
agree_to_access_requestB
Guest: record agreement to terms / NDA on an access request.
Inputs: id (required).
apply_lightbox_membership_assetsA
Push a lightbox membership's pinned assets out to all members (creates per-member copies). Used to broadcast curated picks to a shared lightbox.
Inputs: asset_ids (required), asset_group_membership_id (required).
approve_workflow_stepB
Approve all selected assets in a workflow step, moving them to the next step.
Inputs: id (required), asset_ids (required).
approve_workflow_step_picksA
Approve a curated subset (picks) within a workflow step. Same shape as approve_workflow_step but only the chosen assets advance.
Inputs: id (required), asset_ids (required).
associate_tagging_with_faceA
Associate an existing tagging with a Rekognition face id (link tagging → detected face crop).
Inputs: id (required), face_id (required).
auto_tag_assetA
Run Rekognition / Vision auto-tagging on a single asset. Existing auto-tags are preserved; new ones are appended.
Inputs: id (required).
block_asset_faceA
Block a detected face crop on an asset (creates a "Blocked Face" tag and excludes from future matching).
Inputs: id (required), face_id (required).
bulk_add_tags_to_assetsB
Add the same tag names to many assets at once.
Inputs: asset_ids (required), tag_names (required).
bulk_delete_tagsA
Delete many tags by id in a single call.
Inputs: ids (required).
bulk_download_assetsA
Get a download URL for multiple assets (returns a ZIP file)
Inputs: asset_ids (required), via, size, skip_meta, +1 more.
bulk_edit_assetsA
Update fields on many assets in a single call. Pass an updates object with the same field names as update_asset (title, description, alt_text, caption, credit, copyright, etc.).
Inputs: updates (required), asset_ids (required).
bulk_find_auto_tagsA
Find multiple auto tags by their names at once
Inputs: tag_names (required).
bulk_find_tagsA
Find or stub many tags by name in a single call. Returns existing tags where matched, otherwise unsaved Tag-shaped records the agent can persist.
Inputs: names (required).
bulk_find_taxonomy_tagsA
Find or stub many taxonomy_tags by name in a single call (top-level — searches across taxonomies).
Inputs: names (required).
bulk_remove_tags_from_assetsA
Remove the same tag names from many assets at once.
Inputs: asset_ids (required), tag_names (required).
bulk_set_asset_creator_tagA
Set (or clear with null) the creator tag on many assets in one call.
Inputs: asset_ids (required), creator_tag_id.
bulk_set_asset_rights_packageA
Set (or clear with null) the rights package on many assets in one call.
Inputs: asset_ids (required), rights_package_id.
bulk_update_tagsC
Apply a single change to many tags (set list, attach/detach taxonomy).
Inputs: tag_ids (required), list, add_taxonomy, remove_taxonomy.
cancel_bulk_jobB
Cancel a running bulk job
Inputs: id (required).
can_uploadA
Check if uploads are allowed (storage quota)
Inputs: no named parameters.
check_invite_emailA
Check whether a given email is a valid recipient for a new invite (already has account, already in org, etc.).
Inputs: email (required).
check_tag_nameA
Async uniqueness check for a tag name (e.g., for artwork inventory numbers). Returns { exists: boolean }.
Inputs: name (required).
clear_asset_nsfwA
Mark an NSFW detection as a false positive on an asset; clears the moderation flag and re-indexes.
Inputs: id (required).
create_access_requestA
Create a draft access request (pre-submit). Use submit_access_request to send it.
Inputs: purpose, asset_id, custom_meta, asset_group_id, +1 more.
create_asset_group_inviteA
Invite a user (by email) or existing membership to a collection / lightbox / storage folder.
Inputs: asset_group_id (required), role, email, message, +1 more.
create_bulk_jobA
Create a bulk job for batch operations on assets. Supports multiple operation types:
Tag management: use tag_names + tag_mode (add/remove/replace)
Metadata updates: use description + description_mode (set/append/prepend), rating, rights_package_id
Organization: use add_asset_group_id + add_asset_group_type (Collection/Lightbox/StorageFolder)
AI processing: use run_custom_meta_field_ids + cmf_overwrite_mode (skip/overwrite)
Bulk actions: use destroy_all, restore_all, or generate_alt_text
Inputs: asset_ids (required), rating, tag_mode, tag_names, +22 more.
create_collectionC
Create a new collection
Inputs: name (required), parent_id, description.
create_commentA
Create a new comment on a Lightbox or Collection. Supports markdown and @mentions.
Inputs: id (required), text (required), type (required).
create_contributionB
Create a new contribution portal (named upload link tied to a collection / lightbox / folder).
Inputs: name (required), enabled, message, require_login, +2 more.
create_creator_tagC
Create a new creator tag
Inputs: name (required).
create_crop_presetC
Create a crop preset
Inputs: name (required), width (required), height (required).
create_custom_meta_fieldC
Create a custom metadata field
Inputs: name (required), field_type (required), options, required, +5 more.
create_downloadC
Create a batch download for multiple assets
Inputs: asset_ids (required), size.
create_filter_groupC
Create a new filter group with saved filter configurations
Inputs: name (required), filter_order.
create_inviteB
Invite a user to the organization
Inputs: email (required), role_level (required), note.
create_lightboxC
Create a new lightbox
Inputs: name (required), parent_id, description.
create_meta_downloadA
Kick off a background metadata CSV export. Returns { guid } to poll status.
Inputs: asset_ids (required), columns, send_email, column_preset.
create_personal_access_tokenC
Create a personal access token
Inputs: name (required), scopes.
create_rename_presetC
Create a rename preset
Inputs: name (required), enabled, position, template.
create_rights_packageC
Create a new rights package
Inputs: name (required), rights_class (required), expires, expires_at, +1 more.
create_search_queryA
Save a new search query. The sql field should contain an Elasticsearch SQL WHERE clause.
Inputs: sql (required), name (required), description.
create_storage_folderD
Create a new storage folder
Inputs: name (required), parent_id, description.
create_tagA
Create a new tag. Supports the full enrichment surface (description, sub_type, link, event fields, artwork fields, external-system identifiers).
Inputs: name (required), sku, gtin, link, +34 more.
create_tag_importB
Create a tag-import job. file is the uploaded CSV/XLS file reference (S3 key or upload id).
Inputs: file (required), note, columns, name_column.
create_taxonomyC
Create a new taxonomy
Inputs: name (required), description.
create_taxonomy_tagC
Create a tag within a taxonomy
Inputs: name (required), taxonomy_id (required), parent_id.
create_upload_sessionA
Create a long-lived upload session that you can append files to over multiple upload_file / upload_files calls.
Use this when batch-uploading many files from a script or agent loop, when you want them grouped under one upload in the Mediagraph UI, or when you need to resume after a crash.
Returns the session guid plus aws_key/bucket (used internally for direct-to-S3 multipart). Call set_upload_done with the returned id when the batch is complete.
Inputs: name, note, contribution_id, default_rights_package_id.
create_user_groupC
Create a user group
Inputs: name (required), description.
create_webhookB
Create a webhook to receive event notifications
Inputs: url (required), name (required), note, trash, +5 more.
create_workflowC
Create a new workflow.
Inputs: name (required), enabled, description.
create_workflow_stepB
Create a workflow step (typically attached to a workflow + asset_group).
Inputs: workflow_id (required), name, position, asset_group_id, +1 more.
delete_access_grantC
Delete (revoke) an access grant.
Inputs: id (required).
delete_access_requestB
Delete an access request.
Inputs: id (required).
delete_assetA
Delete (trash) an asset
Inputs: id (required).
delete_asset_group_inviteB
Cancel/revoke an asset group invite.
Inputs: id (required).
delete_auto_tagC
Delete/dismiss an auto tag
Inputs: id (required).
delete_collectionC
Delete a collection
Inputs: id (required).
delete_commentA
Delete a comment. Only the comment author can delete their own comments.
Inputs: id (required).
delete_contributionC
Delete a contribution portal.
Inputs: id (required).
delete_filter_groupB
Delete a filter group
Inputs: id (required).
delete_lightboxB
Delete a lightbox
Inputs: id (required).
delete_personal_access_tokenB
Delete a personal access token
Inputs: id (required).
delete_published_imageA
Delete a single PublishedImage row. Auto-cleans the parent PublishedAsset when the last image is removed.
Inputs: id (required).
delete_rename_presetB
Delete a rename preset
Inputs: id (required).
delete_search_queryB
Delete a saved search query
Inputs: id (required).
delete_tagB
Delete a tag
Inputs: id (required).
delete_taggingA
Remove a tagging (untag an asset)
Inputs: id (required).
delete_tag_importB
Delete a tag-import job
Inputs: id (required).
delete_taxonomyA
Delete a taxonomy. Tags inside it are detached, not deleted.
Inputs: id (required).
delete_taxonomy_tagC
Delete a tag from a taxonomy.
Inputs: id (required), taxonomy_id (required).
delete_user_groupA
Delete a user group. Members are not deleted.
Inputs: id (required).
delete_webhookB
Delete a webhook
Inputs: id (required).
delete_workflowA
Delete a workflow. In-flight workflow_steps may need to be cancelled separately.
Inputs: id (required).
delete_workflow_stepB
Delete a workflow step.
Inputs: id (required).
detect_video_facesA
Trigger face detection for an existing video asset (for videos uploaded before video face tagging shipped).
Inputs: id (required).
disable_my_otpA
Disable TOTP 2FA on the current user account.
Inputs: no named parameters.
disable_personal_access_tokenA
Super-admin: disable a PAT (requests respond with X-PAT-Disabled header)
Inputs: id (required).
disassociate_tagging_with_faceA
Remove the face-crop association from a tagging.
Inputs: id (required).
duplicate_storage_folder_to_collectionA
Super-admin: preview or submit a folder subtree duplication into a Collection using reserved admin worker capacity. Defaults to a server preview. Execute requires a stable idempotency key; never deletes destination content.
Inputs: source (required), destination (required), execute, preview, +2 more.
enable_my_otpA
Enable TOTP 2FA on the current user account by confirming a 6-digit code.
Inputs: otp_attempt (required).
enable_personal_access_tokenA
Super-admin: re-enable a previously disabled PAT
Inputs: id (required).
explain_asset_searchA
Super-admin diagnostic: show which Elasticsearch fields/terms matched a query for a given asset.
Inputs: id (required), q, text_q.
export_custom_meta_fieldsC
Bulk export custom meta fields by ID
Inputs: ids (required).
extend_organization_trialA
Admin: extend a trialing/past_due/canceled subscription
Inputs: id (required), days, until.
finalize_access_requestA
Admin: finalize a submitted access request — approves and grants access.
Inputs: id (required).
find_access_requestA
Find an access request by guid (used in guest-link resolution).
Inputs: guid (required).
find_contributionC
Find a contribution by slug.
Inputs: slug (required).
find_inviteA
Look up an invite by token (for the public invite-acceptance flow).
Inputs: token (required).
find_membershipB
Find a single membership in the current org by username OR user_id.
Inputs: user_id, username.
find_organizationA
Find an organization by slug. Useful when you have a custom-domain URL or know the slug but not the id.
Inputs: slug (required).
generate_asset_alt_textA
Generate accessibility alt text for an asset using AI; saves to the alt_text field.
Inputs: id (required).
generate_urlA
Generate a direct deep-link URL to a Mediagraph entity (asset, collection, lightbox, storage folder, tag, creator tag, share link, or the explore root).
Two host modes:
Custom domain: when the org has one set (e.g. "dam.mer.fm"), URLs use https://{domain}/explore/...
Default: https://mediagraph.io/{org-slug}/explore/...
Path patterns: asset → /explore#/assets/{guid} (hash route) collection → /explore/collections/{slug} lightbox → /explore/projects/{id}-{slug} storage_folder → /explore/folders/{slug} tag, creator_tag → /explore/tags/{id}-{name} share_link → /share-links/{share_code}
Identifier rules:
Pass whichever identifier you already have (guid, slug, id+name, etc.); the tool fetches the entity if needed to derive the rest.
For assets, only guid is needed.
For collections / storage folders, slug works directly.
For lightboxes, the API returns a composite "slug" of the form "{id}-{name}" — pass it as slug.
For tags, pass id (and optionally name for a prettier URL).
Override host with --host (e.g., point at staging) or --base_host (just the fallback).
Inputs: type (required), id, guid, host, +5 more.
get_access_requestC
Get access request details
Inputs: id (required).
get_access_requests_treeA
Hierarchical tree view of access requests by asset group.
Inputs: no named parameters.
get_assetC
Get detailed information about a specific asset
Inputs: id (required), include_meta, include_renditions.
get_asset_added_byA
Find which user added a given asset to a given asset_group (collection / lightbox / folder).
Inputs: id (required), asset_group_id (required).
get_asset_auto_tagsB
Get AI-generated auto tags for an asset
Inputs: id (required).
get_asset_contentB
Get extracted text content for a document asset (PDF/DOCX/etc.).
Inputs: id (required).
get_asset_countsC
Get asset counts with optional filters
Inputs: tags, collection_id, storage_folder_id.
get_asset_downloadB
Get a download URL for an asset
Inputs: id (required), size, watermarked, version_number.
get_asset_event_logB
Audit trail for an asset: every version + who did what, paginated.
Inputs: id (required), page, per_page, request_source.
get_asset_face_taggingsB
Get face taggings for an asset
Inputs: id (required).
get_asset_group_inviteB
Get an asset group invite by id.
Inputs: id (required).
get_asset_metaA
Get extracted EXIF / IPTC / XMP / file metadata for an asset.
Inputs: id (required).
get_asset_ocr_contentB
Get OCR-extracted text from an image asset.
Inputs: id (required).
get_assets_updated_since_last_syncA
Sync helper: returns asset ids that changed since last_sync_at (or since the server-tracked last_external_sync_at if omitted). Useful for export/mirror jobs.
Inputs: any_user, created_via, last_sync_at.
get_asset_versionsB
Get version history for an asset
Inputs: asset_id (required).
get_auto_tagC
Get auto tag details
Inputs: id (required).
get_available_invite_role_levelsA
Return the list of role_level values that the current user is allowed to grant in an invite. Helps prevent BAD_ARGS at create time.
Inputs: no named parameters.
get_bulk_jobB
Get bulk job details and status
Inputs: id (required).
get_bulk_job_queue_positionB
Get queue position for a bulk job
Inputs: id (required).
get_collectionC
Get collection details
Inputs: id (required).
get_collections_treeA
Get collections hierarchy as a tree
Inputs: no named parameters.
get_contributionC
Get contribution details
Inputs: id (required).
get_custom_meta_fieldB
Get custom meta field details
Inputs: id (required).
get_downloadC
Get download status and URL
Inputs: token (required).
get_filter_groupC
Get filter group details
Inputs: id (required).
get_lightboxB
Get lightbox details
Inputs: id (required).
get_lightboxes_treeB
Get lightboxes hierarchy as a tree
Inputs: no named parameters.
get_membershipB
Get membership details by ID
Inputs: id (required).
get_meta_download_columnsA
Get the column catalog for metadata exports (grouped + IPTC + custom meta fields), plus the default basic set
Inputs: no named parameters.
get_meta_importC
Get metadata import job details
Inputs: id (required).
get_my_otp_uriA
Get the otpauth:// URI for setting up TOTP 2FA on the current user account (encode in a QR code).
Inputs: no named parameters.
get_notification_countA
Get unread notification count
Inputs: no named parameters.
get_organizationA
Get details about an organization by ID
Inputs: id (required).
get_organization_abilitiesA
Get the current user's role-derived abilities (manage Asset, view_details Tag, etc.) in an organization. Pair with INSUFFICIENT_SCOPE errors so you can distinguish role denial from missing token scope.
Inputs: id (required).
get_pending_membership_requests_countA
Count of pending membership requests (for badging admin dashboards).
Inputs: no named parameters.
get_popular_assetsD
Get popular assets
Inputs: page, per_page.
get_recent_tag_eventsA
Top 10 most recent tag activity events (no pagination).
Inputs: no named parameters.
get_rename_presetA
Get a rename preset
Inputs: id (required).
get_rights_packageC
Get rights package details
Inputs: id (required).
get_search_queryC
Get search query details
Inputs: id (required).
get_selected_assetsA
Fetch full asset records for an explicit ID list in one call. Use after search_assets returned a set of IDs and you want full attributes without N round-trips.
Inputs: ids (required), aggregates_only.
get_storage_folderB
Get storage folder details
Inputs: id (required).
get_storage_folders_treeA
Get storage folders hierarchy as a tree
Inputs: no named parameters.
get_tagC
Get tag details
Inputs: id (required).
get_tag_associated_facesA
List the face crops currently associated with a person tag (across the org).
Inputs: id (required).
get_tag_eventsB
List recent tag activity events for the org. Optionally filter by year/month.
Inputs: page, year, month, per_page.
get_taggingB
Get details of a specific tagging (tag-to-asset relationship)
Inputs: id (required).
get_tag_importC
Get a tag-import job
Inputs: id (required).
get_tag_import_tagsA
List tags created/updated by a tag-import job
Inputs: id (required), page, per_page.
get_taxonomyC
Get taxonomy details
Inputs: id (required).
get_taxonomy_tags_treeA
Hierarchical tree view of all taxonomy_tags within a taxonomy (parent → children).
Inputs: taxonomy_id (required).
get_taxonomy_tags_visible_asset_countsA
Count assets visible-to-current-user under each taxonomy_tag id (for displaying counts in a tree view).
Inputs: taxonomy_id (required), taxonomy_tag_ids (required).
get_trashed_assetsC
Get trashed assets
Inputs: page, per_page.
get_user_groupA
Get a user group by id (members + permissions).
Inputs: id (required).
get_webhookB
Get webhook details
Inputs: id (required).
get_webhook_logsC
Get webhook delivery logs
Inputs: id (required), page, per_page.
get_workflowC
Get workflow details
Inputs: id (required).
get_workflow_stepA
Get a workflow step by id.
Inputs: id (required).
grant_organization_cai_budgetC
Super-admin: grant free CAI budget to an organization
Inputs: id (required), amount, description.
ignore_asset_face_toggleA
Toggle the per-asset "ignore" state on a detected face id. Useful for hiding low-confidence detections without blocking the face globally.
Inputs: id (required), face_id (required).
ignore_asset_unidentified_facesA
Hide all unidentified (unmatched) face crops on an asset.
Inputs: id (required).
list_access_grantsA
List access grants (the records produced when an access request is finalized).
Inputs: page, per_page.
list_access_requestsC
List access requests and grants
Inputs: q, page, type, per_page, +1 more.
list_asset_group_invitesB
List pending and accepted invitations to collections, lightboxes, and storage folders.
Inputs: page, per_page.
list_auto_tagsB
List AI-generated auto tags
Inputs: q, page, per_page.
list_bulk_jobsC
List bulk jobs
Inputs: page, per_page.
list_collectionsC
List collections in the organization
Inputs: q, page, per_page, parent_id.
list_commentsA
List comments on a Lightbox or Collection
Inputs: id (required), type (required), page, per_page.
list_contributionsA
List contribution portals (upload links). Use contribution_id with upload_file/upload_files to upload to a specific storage folder or lightbox.
Inputs: q, page, per_page.
list_creator_tagsC
List creator/photographer tags
Inputs: q, page, per_page.
list_crop_presetsC
List crop presets
Inputs: page, per_page.
list_custom_meta_fieldsC
List custom metadata fields
Inputs: q, page, per_page.
list_featured_contributionsA
List featured contribution portals (those highlighted in the org UI).
Inputs: no named parameters.
list_filter_groupsC
List saved filter groups
Inputs: page, per_page.
list_group_contributionsB
List contributions tied to a collection / lightbox / folder.
Inputs: no named parameters.
list_ingestionsC
List ingestion jobs
Inputs: page, per_page.
list_invitesC
List pending invites
Inputs: q, page, per_page.
list_lightbox_contributionsB
List contributions tied to lightboxes.
Inputs: no named parameters.
list_lightboxesB
List lightboxes in the organization
Inputs: page, per_page, parent_id.
list_link_contributionsA
List standalone (link-only) contributions.
Inputs: no named parameters.
list_membership_requestsA
List pending requests from users asking to join the current org.
Inputs: page, per_page.
list_membershipsC
List organization memberships
Inputs: page, per_page.
list_meta_downloadsB
List background metadata-export jobs
Inputs: page, dates, user_id, per_page.
list_meta_importsC
List metadata import jobs
Inputs: q, page, per_page.
list_my_invitesA
List pending org invitations addressed to the current user.
Inputs: no named parameters.
list_my_organizationsA
List every organization the current user belongs to (across orgs). Useful for multi-tenant agents picking which org to operate in.
Inputs: no named parameters.
list_notificationsC
List notifications
Inputs: page, per_page.
list_personal_access_tokensA
List personal access tokens
Inputs: page, per_page.
list_rename_presetsB
List rename presets
Inputs: page, enabled, per_page.
list_rights_packagesB
List rights packages for managing asset usage rights
Inputs: page, per_page.
list_search_queriesB
List saved search queries
Inputs: page, per_page.
list_storage_foldersC
List storage folders
Inputs: page, per_page, parent_id.
list_tag_importsB
List tag-import jobs
Inputs: page, per_page.
list_tagsC
List tags in the organization
Inputs: q, page, per_page, tag_import_id.
list_taxonomiesB
List taxonomies (controlled vocabularies)
Inputs: page, per_page.
list_taxonomy_tagsB
List tags within a taxonomy
Inputs: taxonomy_id (required), page, per_page, parent_id.
list_uploadsC
List upload sessions
Inputs: page, per_page.
list_user_groupsC
List user groups
Inputs: q, page, per_page.
list_webhooksB
List webhooks
Inputs: q, page, per_page.
list_workflowsC
List workflows
Inputs: page, per_page.
list_workflow_stepsA
List workflow steps (the user-facing approval queue).
Inputs: page, per_page.
mark_organization_cai_invoice_paidB
Super-admin: mark an open CAI invoice as paid out-of-band
Inputs: id (required).
merge_tagsA
Merge one tag into another. With set_synonym=true, the source tag is preserved as a synonym of the target instead of being deleted.
Inputs: id (required), target_tag_id (required), set_synonym.
preview_rename_bulk_jobA
Preview the filenames a rename bulk job will produce, before submitting it.
Inputs: asset_ids (required), rename_preset_id (required), custom_text, global_start, +2 more.
reauthorizeA
Re-run the OAuth authorization flow. Use this to switch to a different Mediagraph organization or re-authenticate.
Inputs: no named parameters.
remove_asset_auto_tagB
Dismiss a specific auto-tag from this asset (does not delete the auto-tag globally).
Inputs: id (required), auto_tag_id (required).
remove_assets_from_groupA
Remove many assets from a collection / lightbox / storage folder at once.
Inputs: asset_ids (required), asset_group_id (required).
remove_lightbox_membership_assetsB
Remove pinned-assets from a lightbox membership (counterpart to apply).
Inputs: asset_ids (required), asset_group_membership_id (required).
remove_tag_face_creator_tagB
Unlink the creator-tag association from a person tag.
Inputs: id (required).
remove_tag_face_membershipC
Remove the user-membership association from a person tag.
Inputs: id (required).
remove_tag_taxonomiesA
Detach a tag from all taxonomies it belongs to.
Inputs: id (required).
reorder_rename_presetsB
Reorder rename presets by moving one from oldIndex to newIndex
Inputs: newIndex (required), oldIndex (required).
resend_inviteB
Resend an invite email
Inputs: id (required).
reset_tag_faceA
Clear face-tagging state on a person tag and re-enqueue Rekognition indexing.
Inputs: id (required).
restore_assetA
Restore a trashed asset (undo delete_asset).
Inputs: id (required).
revert_assetB
Revert an asset to a previous version
Inputs: id (required), version (required).
revoke_access_requestB
Admin: revoke a previously granted access request.
Inputs: id (required).
run_asset_aiA
Invoke an AI-enabled custom meta field action on an asset (e.g., LLM-driven extraction, classification, or description).
Inputs: id (required), custom_meta_field_id (required).
search_asset_facesB
Run face search on an asset using the org-wide face index; matches detected faces to indexed person tags. Reindexes the asset on success.
Inputs: id (required).
search_assetsA
Search for assets using filters and advanced query operators.
ADVANCED SEARCH QUERY SYNTAX (for the 'q' parameter):
Basic: Just type a term to search all fields (e.g., "dog")
Exclude: Use NOT or minus to exclude (e.g., "NOT dog" or "-dog")
Combine: Use AND, OR, NOT (e.g., "dog AND cat", "dog OR cat", "dog NOT cat")
Field search: Use field:value syntax (e.g., "tag_text:nature", "filename.keyword:IMG_1234.jpg")
Wildcards: Use * (zero or more chars) or ? (single char) (e.g., "tag_text:part*", "tag_text:?artial")
Existence: Use field:** to find assets with any value, NOT field:** for empty (e.g., "NOT tag_text:**" finds untagged assets)
Complex: Use parentheses for grouping (e.g., "(dog OR cat) AND ext:jpg")
NOTE on multi-word queries: the API uses Elasticsearch cross_fields, so a multi-word query like "red barn" can match if "red" appears in one field and "barn" appears in another. Quote phrases ("red barn") to require both terms in the same field.
Sort: pass either 'order' or its alias 'direction' (asc/desc). Results have an implicit id:asc tiebreaker (except when using a custom sort).
COMMON SEARCH FIELDS:
tag_text: Keywords/tags
filename.keyword: Exact filename
description: Asset description
title: Asset title
ext: File extension
creator_text: Creator/photographer name
copyright: Copyright text
city, state, country: Location fields
Inputs: q, gps, ids, exts, +16 more.
search_assets_visualA
Search for assets and display results in an interactive visual gallery.
This tool provides a rich visual interface for browsing search results with:
Thumbnail grid with hover previews
Click to view full asset details
Inline editing of metadata
Rating, tagging, and download options
Pagination controls
Use this when the user wants to visually browse or explore assets.
Inputs: q, gps, ids, exts, +13 more.
search_membershipsA
Search memberships within a comment context (collection / lightbox) — used for assignee pickers and @-mention lookups in commenting flows.
Inputs: q, page, per_page, commentable_id, +1 more.
set_access_request_custom_metaB
Set a custom meta field value on an access request (mirrors set_asset_custom_meta).
Inputs: id (required), custom_meta_field_id (required), text, value, +2 more.
set_asset_custom_metaA
Write to a custom meta field on an asset. The field's shape determines which value param to pass:
free (free-text): pass
value(ortext)select (single-pick): pass
custom_meta_value_idmulti (multi-pick): pass
custom_meta_value_ids(array)
Pass none of value/text/*_id to clear the field. The asset is reindexed on success.
Inputs: id (required), custom_meta_field_id (required), text, value, +2 more.
set_asset_preview_image_from_timeA
For a video asset: set the poster/preview image from the frame at seconds into the video.
Inputs: id (required), seconds (required).
set_main_face_for_taggingA
Promote a tagging to the canonical face for its tag. Used after tag_asset_face to pick which crop represents the person.
Inputs: id (required).
set_tag_face_creator_tagA
Link a person tag to a creator tag by name. Photos created by that creator gain the linked person tag automatically.
Inputs: id (required), name (required).
set_tag_face_membershipA
Associate a person tag with a user (by email). The user becomes the canonical "face" for the tag — useful for faceless tags that need to point to a real person.
Inputs: id (required), email (required).
set_upload_doneA
Finalize an upload session, marking it as complete. Triggers any post-upload hooks (notifications, contribution acceptance, etc.). Call this after the last upload_file/upload_files in a batch you opened with create_upload_session.
Inputs: id (required).
slice_new_assetA
Slice a video asset between start and end (seconds) and queue the result as a brand-NEW asset (optionally added to a lightbox).
Inputs: id (required), end (required), start (required), lightbox_id.
slice_new_asset_versionA
Slice a video asset between start and end (seconds) and queue the result as a NEW VERSION of the same asset. Async — poll the asset.
Inputs: id (required), end (required), start (required).
start_tag_importA
Start processing a tag-import job once it is in the analyzed state
Inputs: id (required).
submit_access_requestD
Submit an access request
Inputs: id (required).
tag_asset_faceA
Manually tag a detected face crop on an image asset and index it into Rekognition for org-wide face matching.
Workflow for "upload a headshot for a person tag":
Upload the headshot via upload_file (optionally with the person tag attached).
Call get_asset_face_taggings to get the face_id of the detected face crop.
Call tag_asset_face with the person tag's id (or a new name) + that face_id.
After indexing, future uploads automatically run face matching against this person.
Inputs: id (required), face_id (required), name, tag_id.
tag_video_faceC
Manually tag a face track in a video; indexes the cropped frame into Rekognition.
Inputs: id (required), person_index (required), name, tag_id.
transfer_lightbox_ownershipA
Transfer ownership of a lightbox to another user (by user id).
Inputs: id (required), user_id (required).
update_access_requestC
Update an in-progress access request.
Inputs: id (required), purpose, custom_meta.
update_assetC
Update asset metadata
Inputs: id (required), city, notes, state, +9 more.
update_asset_descriptionA
Patch only the description field on an asset (lighter than update_asset; does not touch other fields).
Inputs: id (required), description (required).
update_asset_group_inviteB
Update an asset group invite (e.g. change role).
Inputs: id (required), role, message.
update_collectionD
Update a collection
Inputs: id (required), name, description.
update_commentA
Update a comment. Only the comment author can update their own comments.
Inputs: id (required), text (required).
update_contributionC
Update a contribution portal.
Inputs: id (required), name, enabled, message, +2 more.
update_filter_groupC
Update a filter group
Inputs: id (required), name, filter_order.
update_filter_group_visibilityB
Update the visibility of a specific filter within a filter group
Inputs: id (required), name (required), type (required), visible (required).
update_inviteB
Update an invite (change role or note)
Inputs: id (required), note, role_level.
update_lightboxC
Update a lightbox
Inputs: id (required), name, description.
update_membershipD
Update a membership
Inputs: id (required), role.
update_membership_statusA
Update the AASM status of a membership (e.g. activate, suspend). Different from update_membership which patches role_level / preferences.
Inputs: id (required), status (required).
update_meta_downloadA
Toggle the send_email flag on an in-progress metadata export
Inputs: guid (required), send_email (required).
update_rename_presetC
Update a rename preset
Inputs: id (required), name, enabled, position, +1 more.
update_search_queryA
Update a saved search query name or description. Note: The SQL query cannot be changed after creation.
Inputs: id (required), name, description.
update_tagB
Update a tag — accepts every enrichment field (description, sub_type, link, event fields, artwork fields, external-system links, synonym graph).
Inputs: id (required), sku, gtin, link, +37 more.
update_tag_importC
Update a tag-import job
Inputs: id (required), note, columns, name_column.
update_tag_import_mappingC
Set the column mapping for a tag-import job
Inputs: id (required), column (required).
update_taxonomyC
Update a taxonomy (name, description, etc.).
Inputs: id (required), name, description.
update_taxonomy_tagC
Update a tag inside a taxonomy.
Inputs: id (required), taxonomy_id (required), name, parent_id.
update_user_groupC
Update a user group (name, description, etc.).
Inputs: id (required), name, description.
update_workflowD
Update a workflow.
Inputs: id (required), name, enabled, description.
update_workflow_stepC
Update a workflow step.
Inputs: id (required), name, position, preserve_subfolders.
upload_asset_transcriptB
Upload a closed-caption / transcript text for a video asset (e.g. WebVTT or plain text).
Inputs: id (required), transcript (required).
upload_fileA
Upload a file to Mediagraph. Two body modes (file_path or file_data) and three session modes:
Body modes:
Local file: Provide file_path for files on the user's local filesystem
Direct upload: Provide file_data (base64-encoded) with filename for files from other sources
Session modes (mutually exclusive):
Default: a fresh one-shot upload session is created and finalized for this single file.
upload_guid: append to an existing session created via create_upload_session. The session is NOT finalized; call set_upload_done when your batch is complete.
contribution_id: upload via a contribution's configured destination (storage folder / lightbox).
Files >16 MiB automatically use S3 multipart upload (parallel parts, retry per part); smaller files go through a single signed PUT.
Inputs: filename, file_data, file_path, upload_guid, +1 more.
upload_filesA
Upload multiple files from the local filesystem in one operation.
Session behavior:
Default: creates one fresh session, uploads all files into it, finalizes it.
upload_guid: appends to an existing session; does NOT finalize (caller's job).
contribution_id: routes the new session through a contribution.
Files >16 MiB use S3 multipart automatically.
Inputs: file_paths (required), upload_guid, contribution_id.
whoamiA
Get information about the currently authenticated user and organization
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 277 tools
With 277 tools, many operations are adjacent or overlapping: add_tags_to_asset vs bulk_add_tags_to_assets vs create_bulk_job tag mode; update_asset vs update_asset_description vs bulk_edit_assets; and numerous list/find/search variants across tags, faces, shares, access requests, and contributions. Descriptions help, but the sheer density of near-duplicate tools makes misselection likely.
Overwhelmingly consistent snake_case with predictable verb_noun families such as list_*, get_*, create_*, update_*, delete_*, and bulk_*. A few exceptions like whoami, reauthorize, and compound verbs such as apply_lightbox_membership_assets are readable and do not seriously undermine the pattern.
277 tools is far beyond an appropriate scope, even for a full DAM platform, and many single/bulk/resource-specific variants could be consolidated. This is an extreme count mismatch under the rubric.
The surface covers core DAM lifecycle areas broadly: assets, collections, lightboxes, folders, tags/taxonomies, uploads, AI/face tagging, workflows, sharing, access requests, memberships, webhooks, and organization management. Minor gaps remain, such as storage-folder update/delete and notification read actions, but most workflows have a path.
Maintenance
Related MCP Connectors
MCP server exposing the YourImageShare upload API (upload/list/delete) as tools for AI agents.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceExposes the inmydata agents SDK as an MCP server, enabling AI agents to access inmydata's powerful data querying capabilities through a standardized interface.-
- AlicenseNot gradedqualityCmaintenanceMCP server for searching and retrieving Creative-Commons-licensed images and audio from Openverse. Enables AI agents to query open media content.204 npmMIT

Runware MCPofficial
AlicenseNot gradedqualityBmaintenanceMCP server that gives AI agents access to Runware's full API for image, video, audio, 3D, upscaling, and other media generation and processing tasks via natural language.663 npmMIT- FlicenseNot gradedqualityCmaintenanceExposes multimodal analysis tools (text search, image metadata/captions, audio features, video frame sampling) over a local media store via MCP, and includes an optional CrewAI Router/Specialist/Responder client that routes requests by modality.-