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 is determined by the server: after upload Numonic extracts the prompt, workflow and models embedded in the file (e.g. ComfyUI PNG/MP4 metadata) and GetAssetDetails reports them with provenance.lineage_source. prompt_metadata is OPTIONAL — omit it when you do not know how the asset was made (never invent a prompt or agent hash); an asserted empty or "none" value never overrides what extraction finds. IMPORTANT for chat-attached files: developer-mode MCP connectors do not reliably receive a file reference for a file attached directly in chat (OpenAI Apps SDK openai/fileParams hydration is documented for first-party Apps SDK directory apps and is unconfirmed for custom developer-mode connectors — see GitLab #2807). If the user attaches an image/file in chat and asks you to store it, do NOT re-encode a large attachment as asset_data_base64 yourself — a large inline re-encode can run for minutes and get cancelled. Ask the user for a URL to pass via asset_data_url instead, or use asset_storage_ref if the file was already uploaded to a Numonic-issued signed URL.

Search for assets using text queries, semantic similarity, or metadata filters. Bare words and quoted phrases are matched semantically; field:value terms filter on asset metadata. Searchable fields: core (title, description, filename, tag, status, mime_type, dimensions); dates (created, updated: YYYY-MM-DD or a range a..b); generation (tool, prompt, version, job_type, batch_size, parameters, ai, chain); models (model, checkpoint, lora, model_name, model_type, base_model, trigger_word, model_weight; model/checkpoint/lora match any part of the name, e.g. model:flux); ComfyUI (comfyui_node, comfyui_workflow, comfyui_model, comfyui_model_type, comfyui_model_hash); Midjourney (mj_command, mj_version, mj_type, mj_batch). Combine field terms with AND/OR, group them with parentheses, and exclude one with NOT or a leading "-" (-tag:draft). Wildcards (*) and quoted values (prompt:"burnt-out city") are supported. Any other field prefix is ignored and its value searched as plain text. 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.

Not available yet: file export over MCP produces no file, so this tool validates its input and returns an EXPORT_UNAVAILABLE error. To share images, use PublishCollection, which returns a public link to signed copies; to download files, use the Numonic app or the REST endpoint POST /api/v1/assets/export.

List available export presets with their default options. Returns the preset configurations used by privacy-aware exports in the Numonic app and REST API (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, including how it was made. Answers 'which prompt, model and workflow produced this?' directly — no download needed: `prompts.positive`/`prompts.negative` hold the prompt, `models[]` lists every model the workflow loaded (name, type such as checkpoint/unet/lora/vae, loader node_id), `workflow.workflow_json` is the full ComfyUI graph (with `workflow.tool_name`, `node_count`, `custom_nodes`), and `generation_parameters` holds sampler settings (model_name, seed, steps, cfg_scale, sampler, scheduler) when they were read from a standard KSampler node, else null (the graph still has them). `provenance.lineage_source` says where that lineage came from: 'extracted' (read by Numonic from the stored file; `prompts.source`/`workflow.source` are then 'extracted'), 'client_asserted' (only the uploader's claim), or 'unknown' (nothing asserted or found). Also returns title, description, tags, collections, provenance (creation prompt, parent assets), embedding info and copyright. For Model Library records of those models (base model, trigger words, usage) call GetAssetModels. Optionally generates a signed download URL for the original file (valid 5 minutes).

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 the Model Library records for every model used to generate a specific asset (checkpoints, UNETs, LoRAs with weights, VAEs, CLIP, upscalers), with base model, type and detection source. Scoped to your tenant: an asset your tenant does not hold returns no models. For the prompt and ComfyUI workflow graph, call GetAssetDetails.

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 (written when any research field is present, not only pain_hypothesis — #2000) and prospect_deal_s (when trial_start_date or agreed_price is present — #2000). At least one of email / linkedin_url / profile_url / handle / website required (#1997); keying precedence when more than one is present is email > linkedin_url > profile_url > handle > website. Append-only — re-calling adds new satellite rows.

Assign or reassign a prospect's owner (#1999). Append-only — writes a new prospect_owner_s row; never touches prospect_outreach_touch_s, so reassignment does not rewrite touch history. Set independently of prospect_outreach_touch_s.sent_by.

Append a touch to the outbound log and advance the prospect outreach sequence state. channel accepts email, linkedin, discord, github, contact_form, or other (#1998). 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, account substring, or owner (#1999, exact match). Suppressed prospects (suppressed_until in the future) are excluded by default. Default limit 50, max 200. Each result row includes the current owner (null if unassigned).

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/bounced → suppressed, ooo leaves state untouched. bounced (#1998) is a delivery failure, distinct from every refusal classification. reply.refusal_class (#2000) optionally codes a refusal T (timing) or P (problem), only valid alongside a refusal-shaped classification. 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.