MCP Server Reference

Store an asset (file) in Numonic with metadata and lineage. Provide EXACTLY ONE of: base64 bytes (asset_data_base64), a reference to a pre-uploaded object (asset_storage_ref), or an HTTPS URL the Edge Function will fetch server-side (asset_data_url). The URL channel accepts allowlisted hosts only (configured per-deployment via MCP_URL_INGEST_ALLOWLIST; default: signed Supabase URLs + Comfy Cloud + Midjourney CDN + Civitai + Numonic-managed S3). Default size cap 100 MB (MCP_URL_INGEST_MAX_BYTES); default fetch timeout 30s (override per-call via timeout_seconds, max 300). Distinct error codes: URL_EXPIRED, URL_FORBIDDEN_HOST, URL_TOO_LARGE, URL_FETCH_TIMEOUT, URL_CONTENT_TYPE_MISMATCH. Lineage (prompt_metadata) is REQUIRED — every asset must record what generated it.

Search for assets using text queries, semantic similarity, or metadata filters. Supports advanced search grammar with Boolean operators (AND/OR/NOT), field-specific queries (tool:midjourney, tag:approved), wildcards (*), ranges, and negation. See /docs/search for full syntax.

Retrieve the evolution chain (parent→child lineage) for a Midjourney asset, showing how it evolved through variations and upscales.

Discover all Midjourney assets created within a time window of a given asset, grouped by temporal proximity to form a "creative session".

Reverse lookup: finds if an asset is in ANY published collection and returns the public URL. Returns one of three states: (1) Asset IS published with public_url, collection_path, preset, published_at; (2) Asset NOT published but in collections: lists collection paths; (3) Asset NOT in any collection: empty collections array.

Create a new annotation on a ComfyUI workflow node with full audit trail.

Retrieve all annotations for a specific ComfyUI workflow node with author information.

Update an existing annotation by creating a new version via supersession chain (effectivity pattern).

Delete (soft delete) an annotation - marks it as deleted without removing data.

List collections as a hierarchical tree for organizing assets. Supports filtering by parent path and depth.

Create a new collection with optional parent for hierarchy. Collections organize assets into folders with up to 5 levels of nesting.

Add one or more assets to a collection with optional position and role.

Get assets in a collection with membership metadata (position, role, added date).

Create a branch or snapshot of a collection. Copies all asset memberships to the new collection. Useful for versioning, client deliveries, or template instances.

Move a collection (and all descendants) to a new parent location in the hierarchy.

Publish a collection with specified privacy and publish presets, making assets publicly accessible. Applies ADR-057 metadata stripping rules and generates public URLs.

Remove a collection from public access. Published assets are marked as unpublished and deleted from public storage.

Get publication status and public URLs for all assets in a collection. Returns whether the collection is published, publication metadata, and URLs for each published asset.

Export assets with configurable privacy-aware metadata stripping for EU AI Act and CA SB 942 compliance. Supports presets (share, portfolio, client, archive, custom) or legacy export configurations.

List available export presets with their default options and compliance status. Returns preset configurations for privacy-aware asset exports following ADR-057.

Retrieve storage usage details for a tenant including bytes used, GB used, storage limit, percentage used, and over-limit status. Helps monitor storage consumption and enforce storage quotas.

Retrieve search analytics summary with health assessment (green/amber/red) for monitoring search quality. Returns zero-result rate, latency percentiles (P50/P95/P99), query-type breakdown, and top zero-result queries. Health thresholds: zero-result rate (<15% green, 15-25% amber, >25% red), P95 latency (<500ms green, 500-1000ms amber, >1000ms red).

Execute a multi-stage asset pipeline. Compose select, filter, transform, action, output, and summarize stages into a single operation. Use dry_run: true to preview changes before committing. Stages by category: SELECT: search, collection, ids, diff (set comparison). FILTER: where, sort, limit, deduplicate, sample. TRANSFORM: set_tag, remove_tag, set_field, regex_replace, compute, set_visibility, set_owner, enrich (stub), approve (stub). ACTION: add_to_collection, move, delete, archive. OUTPUT: export (ADR-057 privacy-aware), notify (stub), tee (passthrough fan-out). SUMMARIZE: count, group_by, stats, histogram. Output stages require confirm: true and are skipped during dry-run. Summarize stages execute during dry-run to provide aggregation previews.

Create or update a named saved pipeline. Provide pipeline_definition_h to update an existing pipeline (SCD Type 2 versioning preserves full edit history). Omit it to create a new pipeline. Pipelines are identified by slug (derived from name) and stored with full stage definitions.

List saved pipelines for the current tenant. Returns pipeline metadata including name, stage count, tags, and default execution settings. Use pipeline_definition_h from results with RunSavedPipeline to execute.

Execute a saved pipeline by ID or name. Supports overriding default_dry_run and default_timeout_ms at run time. Returns the same execution trace as ExecutePipeline. Provide either pipeline_definition_h (40-char hex) or pipeline_name (resolved automatically).

List available pipeline templates for the current tenant. Returns system templates (available to all tenants) plus any tenant-specific templates. Use the pipeline_definition_h from results with POST /api/v1/pipelines/templates to clone a template into a new saved pipeline.

Execute a single SELECT-category pipeline stage. SELECT stages are entry points that produce an initial asset set. Supported stage_type values: search (text query), collection (load from collection path), ids (explicit asset hashes), diff (set difference between two sub-selects).

Execute a single FILTER-category pipeline stage on a set of assets. Supported stage_type values: where (field filter), sort (order by field), limit (cap result count), deduplicate (remove duplicates), sample (random subset).

Execute a single TRANSFORM-category pipeline stage on a set of assets. Modifies asset metadata or triggers AI enrichment. Supported stage_type values: set_tag, remove_tag, set_field, regex_replace, compute, set_visibility, set_owner, enrich, approve.

Execute a single ACTION-category pipeline stage on a set of assets. Performs structural operations like moving, deleting, or archiving assets. Supported stage_type values: add_to_collection, move, delete, archive.

Execute a single OUTPUT-category pipeline stage on a set of assets. Produces outputs like exports, notifications, or tee copies. Supported stage_type values: export, notify, tee.

Execute a single SUMMARIZE-category pipeline stage on a set of assets. Produces aggregate data and statistics. Supported stage_type values: count, group_by, stats, histogram.

Create an automation rule that triggers a saved pipeline on events, schedules, or watch intervals. Provide pipeline_definition_h (40-char hex) or pipeline_name (resolved automatically). Trigger types: event (fires on asset/pipeline events), schedule (cron-based), watch (periodic query check).

List automation rules for the current tenant with optional filters. Returns rule metadata including name, trigger type, enabled status, and linked pipeline.

Manually trigger automation rule processing. For schedule/watch: evaluates all due rules for the tenant. For event: dispatches to matching event-based rules. Returns execution results for each triggered rule.

Register a new webhook subscription to receive event notifications. Returns webhook ID and signing secret (shown once). Supports events: pipeline.completed, pipeline.failed, pipeline.export.completed, test.ping.

Retrieve comprehensive details for a specific asset by its SHA-1 hash. Returns metadata, tags, collections, provenance, embedding info, and copyright. Optionally generates a short-lived signed download URL.

Add or remove a set of tags across up to 100 assets in one call. Per-asset behaviour: 'add' merges into the existing tag set (deduped); 'remove' deletes the listed tags from each asset. Assets whose tag set does not change are skipped silently and reported as unchanged in the response. Tenant-scoped; uses the same RLS path as PATCH /api/v1/assets/bulk-tag.

Partial update of a single asset's scalar metadata: description, title, and/or tags. Tag update on this tool REPLACES the entire existing tag set; for incremental add/remove operations across multiple assets use BulkUpdateAssetTags. At least one of description, title, or tags must be provided. Tenant-scoped; uses the same RLS path as PATCH /api/v1/assets/[assetH].

Export a collection as a PDF document. Returns the PDF as a base64-encoded string along with page count and processing time metadata. The web API handles layout, pagination, and optional watermark removal.

Add a rich-text card (slide) to a collection. Text cards are rendered as full slides in PDF exports and can contain a heading, body text, bullet points, and an accent callout. Supports dark, gradient, and light backgrounds with optional hex accent color.

Search the Model Library for models (LoRAs, checkpoints, UNETs, etc.) by name, type, or base architecture. Returns model entities with metadata, not assets. Use GetAssetModels to find assets by model.

Get full details for a specific model including metadata, version history, asset usage count, and preview count.

Get all models used to generate a specific asset, including LoRA weights and detection source.

Manually link a model to an asset (for non-ComfyUI sources where automatic detection is not available).

Get version history for a model, including training steps, quality scores, and recommended flag.

Add a version to a model with training metadata, quality score, and recommended flag.

Create an experiment collection for structured image comparison workflows (model benchmarking, prompt A/B testing, style evaluation). Returns the experiment collection hash.

Add an asset to an experiment as a run with full context (condition, seed, prompt, model, domain params).

Score an experiment run on user-defined dimensions. Creates an evaluation annotation. Dimensions are experiment-defined (e.g., quality, adherence, coherence).

Create a pairwise A/B comparison between two experiment runs, recording which item wins on each scoring dimension.

Get aggregated experiment results: run count, condition breakdown, outcome tag distribution, and comparison count.

Create a new prompt in the Prompt Library. Returns the prompt hash and version info.

Get a prompt by hash ID with full version history and evaluations.

Search prompts with optional category, target_model filters, and pagination.

Render a prompt template by substituting {{variable}} placeholders with provided values.

Register or update a cold-outreach prospect: writes prospects_h hub + tenant scoping link + prospect_profile_s, and optionally prospect_research_s when pain_hypothesis is supplied. Either email or linkedin_url required. Append-only — re-calling adds new satellite rows.

Append a touch (email or LinkedIn message) to the outbound log and advance the prospect outreach sequence state. Both writes are append-only.

Return full prospect state: latest profile + research + state + suppression, plus all touches and replies, plus contact_link if hand-off has occurred.

Filter prospects by campaign, current sequence status, minimum ICP score, vertical, or account substring. Suppressed prospects (suppressed_until in the future) are excluded by default. Default limit 50, max 200.

Suppress a prospect with a reason and end-date. Marks all active sequences for the prospect as suppressed. cold-outreach-studios convention: 12 months for unsubscribe / not_interested / wrong_person; reengage_date from the reply for not_now.

Record an inbound reply with cold-outreach-studios reply-triage classification. Advances sequence state: positive → replied, not_now/wrong_person/unsubscribe/not_interested → suppressed, ooo leaves state untouched. On positive reply, mints prospect_to_contact_l so lead-response v0.2 picks up the now-warm contact.

List CRM contacts in a pipeline (community | enterprise | investor) with optional stage and free-text search. Wraps get_pipeline_contacts; returns the latest profile, pipeline stage, activity (last_contacted, next_follow_up), plus pipeline-specific satellite fields (investor: firm_name, investor_type, investment_amount, round, seis_eis_status). Default limit 50, max 200. tenant_id is auto-injected from API key auth.