Developer Documentation

Numonic MCP Server

Connect AI agents to your digital asset library via Model Context Protocol. 37 tools, 5 resources, and 5 guided prompts — ready for Claude, Cursor, and custom agents.

  • 37 Tools
  • JSON-RPC 2.0
  • Streamable HTTP
  • All Tiers (incl. Free)

What is MCP?

Model Context Protocol (MCP) is a standard for connecting AI models to external tools. Think of it as “OpenAPI for AI agents.” Your AI client sends JSON-RPC requests; Numonic executes them and returns structured results.

You don't need to understand the protocol deeply — just configure your client and start calling tools. If you prefer traditional HTTP endpoints, see the REST API Reference. Every MCP tool has a REST equivalent.

For AI Agents

MCP is best when your workflow involves an AI agent making decisions about which operations to call — search, organize, export, automate.

For Automation

Build pipelines that select, filter, transform, and export assets in composable stages — all through structured tool calls.

Privacy-First

Export presets enforce EU AI Act and CA SB 942 compliance. Control exactly what metadata is shared publicly.

Getting Started

1

Create an API Key

In the Numonic dashboard, go to Settings > API Keys and create a new key. Keys are available on all tiers, including free.

Your key will look like napi_a1b2c3d4e5f6... — store it securely. It won't be shown again.

2

Connect Your MCP Client

The Numonic MCP server accepts connections over Streamable HTTP (JSON-RPC 2.0 over HTTP POST):

POST https://<project>.supabase.co/functions/v1/mcp-server

Authenticate with your API key as a Bearer token or via the X-API-Key header.

3

Test the Connection

Send an initialize request to verify everything works:

curl -X POST https://<project>.supabase.co/functions/v1/mcp-server \
  -H "X-API-Key: napi_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": { "protocolVersion": "2025-03-26" },
    "id": 1
  }'

A successful response returns the server capabilities including Numonic-MCP-Server v1.0.0. Then list tools with {"method": "tools/list"}.

Client Configuration

Copy-paste configuration for popular MCP clients.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "numonic": {
      "url": "https://<project>.supabase.co/functions/v1/mcp-server",
      "headers": {
        "Authorization": "Bearer napi_your_key_here"
      }
    }
  }
}

Restart Claude Desktop after saving. You'll see Numonic's 37 tools in the tool picker.

Claude Code (CLI)

Run this command in your terminal:

claude mcp add numonic \
  --transport http \
  --url "https://<project>.supabase.co/functions/v1/mcp-server" \
  --header "Authorization: Bearer napi_your_key_here"

Cursor / Windsurf

Add to your project's .cursor/mcp.json or global MCP settings:

{
  "mcpServers": {
    "numonic": {
      "url": "https://<project>.supabase.co/functions/v1/mcp-server",
      "headers": {
        "Authorization": "Bearer napi_your_key_here"
      }
    }
  }
}

Custom Agents (SDKs)

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport }
  from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('https://<project>.supabase.co/functions/v1/mcp-server'),
  {
    requestInit: {
      headers: { Authorization: 'Bearer napi_your_key_here' },
    },
  }
);

const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

// Search for assets
const result = await client.callTool('SearchAssets', {
  query: 'tool:midjourney AND tag:approved',
  limit: 10,
});
console.log(result.content);

Python

mcp
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client(
    "https://<project>.supabase.co/functions/v1/mcp-server",
    headers={"Authorization": "Bearer napi_your_key_here"},
) as (read_stream, write_stream, _):
    async with ClientSession(read_stream, write_stream) as session:
        await session.initialize()

        # List tools
        tools = await session.list_tools()
        print(f"{len(tools.tools)} tools available")

        # Search for assets
        result = await session.call_tool(
            "SearchAssets",
            arguments={
                "query": "tool:midjourney AND tag:approved",
                "limit": 10,
            },
        )
        print(result.content)

Authentication

All API keys must start with the napi_ prefix. Keys are SHA-256 hashed server-side — Numonic never stores your raw key.

MethodHeaderNote
Bearer tokenAuthorization: Bearer napi_...Required by most MCP clients
API key headerX-API-Key: napi_...Preferred for direct HTTP
Legacy headerapi-key: napi_...Backwards compatibility

Multi-tenant access

If your API key has access to multiple tenants, pass X-Tenant-ID to select which tenant to operate on. If omitted, the key's default tenant is used.

Tools (37)

Atomic operations your agent can call via tools/call. Each tool accepts a JSON arguments object and returns structured results.

Asset Ingestion

Store and ingest assets into Numonic

StoreAsset

Store an asset (file) in Numonic with metadata. Supports base64-encoded data or storage reference.

ParameterTypeRequiredDescription
asset_data_base64stringOptionalBase64-encoded asset data (mutually exclusive with asset_storage_ref)
asset_storage_refstringOptionalReference to pre-uploaded asset in storage (mutually exclusive with asset_data_base64)
mime_typestringRequiredMIME type of the asset (e.g., image/png)
filenamestringRequiredOriginal filename
titlestringOptionalOptional asset title
descriptionstringOptionalOptional asset description
tagsarrayOptionalOptional array of tags

Asset Discovery

Retrieve individual assets, public URLs, and creative sessions

GetMidjourneyEvolutionChain

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

ParameterTypeRequiredDescription
asset_idstringRequiredUUID of the asset to get evolution chain for
max_depthnumberOptionalMaximum depth to traverse (default: 10, max: 50)

GetCreativeSession

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

ParameterTypeRequiredDescription
asset_idstringRequiredUUID of the asset to find session for
time_windowstringOptionalTime window for session discovery (e.g., "2 hours", "30 minutes", "1 day")

GetAssetPublicUrl

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.

ParameterTypeRequiredDescription
tenant_idstringOptionalTenant UUID (optional - auto-injected from API key auth)
asset_hstringRequiredAsset hash (SHA-1, 40 hex chars) to look up

Annotations

Create, read, update, and delete asset annotations

CreateAnnotation

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

ParameterTypeRequiredDescription
workflow_node_idstringRequired40-character hexadecimal workflow node identifier
contentstringRequiredAnnotation text content (1-10000 characters)
content_typestringOptionalContent format type
visibilitystringOptionalVisibility level: private (author only), team (tenant), public (all)

GetAnnotations

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

ParameterTypeRequiredDescription
workflow_node_idstringRequired40-character hexadecimal workflow node identifier
include_resolvedbooleanOptionalInclude resolved annotations in results (default: false)

UpdateAnnotation

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

ParameterTypeRequiredDescription
annotation_idstringRequired40-character hexadecimal annotation identifier
contentstringOptionalUpdated annotation content (optional)
visibilitystringOptionalUpdated visibility level (optional)

DeleteAnnotation

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

ParameterTypeRequiredDescription
annotation_idstringRequired40-character hexadecimal annotation identifier

Collections

Organise assets into named, versioned collections

ListCollections

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

ParameterTypeRequiredDescription
tenant_idstringOptionalTenant UUID (optional - auto-injected from API key auth)
parent_pathstringOptionalOptional filter to list only descendants of this path (ltree format, e.g., "projects.nike")
include_asset_countsbooleanOptionalInclude asset count per collection. Default: true
max_depthnumberOptionalMaximum hierarchy depth to return (1-5). Default: 5

CreateCollection

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

ParameterTypeRequiredDescription
tenant_idstringRequiredUUID of the tenant to create collection in
namestringRequiredCollection name (will be normalized to lowercase alphanumeric)
parent_pathstringOptionalParent collection path (ltree format) or null for root collection
display_namestringOptionalHuman-friendly display name. Auto-generated from name if not provided
descriptionstringOptionalOptional description for the collection
iconstringOptionalOptional icon identifier for UI
colorstringOptionalOptional hex color code (e.g., #3B82F6)

AddToCollection

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

ParameterTypeRequiredDescription
tenant_idstringRequiredUUID of the tenant
collection_pathstringRequiredCollection ltree path to add assets to (e.g., "projects.nike")
asset_hsarrayRequiredArray of asset hashes (SHA-1) to add
positionnumberOptionalOptional starting position for the first asset. Subsequent assets increment.
rolestringOptionalOptional role for all assets (KeyVisual, SupportingElement, ReferenceMaterial, BackgroundAsset, Logo, Variation, Other)

GetCollectionAssets

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

ParameterTypeRequiredDescription
tenant_idstringRequiredUUID of the tenant
collection_pathstringRequiredCollection ltree path to get assets from
include_nestedbooleanOptionalInclude assets from all descendant collections. Default: false
limitnumberOptionalMaximum number of assets to return. Default: 50
offsetnumberOptionalOffset for pagination. Default: 0
order_bystringOptionalSort order: "position" or "added_at". Default: "position"

BranchCollection

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

ParameterTypeRequiredDescription
tenant_idstringRequiredUUID of the tenant
source_pathstringRequiredSource collection ltree path to branch from
new_namestringOptionalName for the branch. Auto-generated as "<source>_<type>_<timestamp>" if not provided
branch_typestringOptionalType of branch: "branch" (editable), "snapshot" (frozen), "template_instance". Default: "branch"
snapshot_labelstringOptionalHuman-readable label for snapshots (e.g., "v1.0", "Client Review")

MoveCollection

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

ParameterTypeRequiredDescription
tenant_idstringRequiredUUID of the tenant
source_pathstringRequiredSource collection ltree path to move
new_parent_pathstringOptionalNew parent ltree path. Null or empty to move to root level.

Publishing

Publish collections and retrieve public-access URLs

PublishCollection

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

ParameterTypeRequiredDescription
tenant_idstringRequiredUUID of the tenant
collection_hstringRequiredCollection hash (SHA-1, 40 hex chars) to publish
privacy_presetstringOptionalPrivacy preset for metadata stripping (ADR-057): share (strip workflow/models/GPS), portfolio (default, keeps attribution), client (business delivery), archive (keep all metadata)
publish_presetstringOptionalImage optimization preset: web-standard (default), high-quality, thumbnail

UnpublishCollection

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

ParameterTypeRequiredDescription
tenant_idstringRequiredUUID of the tenant
collection_hstringRequiredCollection hash (SHA-1, 40 hex chars) to unpublish

GetCollectionPublicUrls

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.

ParameterTypeRequiredDescription
tenant_idstringRequiredUUID of the tenant
collection_hstringRequiredCollection hash (SHA-1, 40 hex chars) to get public URLs for

Export

Export assets using configurable presets

ExportAssets

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.

ParameterTypeRequiredDescription
tenant_idstringRequiredUUID of the target tenant for this export operation
asset_hsarrayRequiredArray of Asset Hashes (SHA1) to be exported
presetstringOptionalExport preset: share (social media, max privacy), portfolio (keeps attribution), client (business delivery), archive (full metadata), custom (user-defined)
optionsobjectOptionalCustom options (only when preset is "custom"). Fine-grained control over metadata stripping.
formatstringOptionalOutput format (preserve = keep source format)
export_configuration_hstringOptionalLegacy: Export Configuration Hash. Mutually exclusive with preset.

ListExportPresets

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

ParameterTypeRequiredDescription
tenant_idstringRequiredTenant UUID (for tenant-specific presets if available)

Analytics

Query search analytics and tenant storage metrics

GetTenantStorageDetails

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.

ParameterTypeRequiredDescription
tenant_idstringOptionalOptional: UUID of the tenant to query. If omitted, uses the tenant_id from auth context (current user's tenant).

GetSearchAnalytics

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).

ParameterTypeRequiredDescription
periodintegerOptionalNumber of days to aggregate (1-90). Default: 7.
tenant_idstringOptionalOptional: UUID of the tenant to query. If omitted, returns analytics for all tenants or current user's tenant.

Pipelines

Execute, save, list, and run reusable processing pipelines

ExecutePipeline

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.

ParameterTypeRequiredDescription
stagesarrayRequiredOrdered list of pipeline stages. Must start with a select stage (search, collection, ids, or diff).
dry_runbooleanOptionalPreview what would happen without executing mutations. Transform/action stages show simulated side effects. Output stages are skipped. Summarize stages execute to provide aggregation previews. Default: false.
timeout_msnumberOptionalMaximum execution time in milliseconds (1000-60000). Default: 30000.

SavePipeline

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.

ParameterTypeRequiredDescription
namestringRequiredPipeline name (used to generate URL-safe slug). Must be unique per tenant.
stagesarrayRequiredOrdered pipeline stage definitions (same format as ExecutePipeline stages)
descriptionstringOptionalHuman-readable description of what this pipeline does
default_dry_runbooleanOptionalDefault dry_run setting when run without override (default: false)
default_timeout_msnumberOptionalDefault timeout in ms, 1000-60000 (default: 30000)
tagsarrayOptionalLabels for organizing pipelines (e.g., ["weekly", "client-delivery"])
pipeline_definition_hstringOptional40-char hex hash of existing pipeline to update. Omit to create new.

ListPipelines

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.

ParameterTypeRequiredDescription
tagsarrayOptionalFilter by tags (e.g., ["weekly"])

RunSavedPipeline

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).

ParameterTypeRequiredDescription
pipeline_definition_hstringOptional40-char hex hash of the pipeline to run
pipeline_namestringOptionalPipeline name (alternative to pipeline_definition_h). Resolved to hash automatically.
dry_runbooleanOptionalOverride the saved default_dry_run. Defaults to pipeline's saved setting.
timeout_msnumberOptionalOverride the saved default_timeout_ms (1000-60000)
varsobjectOptionalRuntime variable injection (merged into pipeline context vars)

ListPipelineTemplates

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.

Pipeline Stages

Execute individual pipeline stages (select, filter, transform, etc.)

SelectStage

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).

ParameterTypeRequiredDescription
stage_typestringRequiredThe SELECT stage type to execute
configobjectRequiredStage-specific configuration. search: { query: "tag:approved" }. collection: { path: "projects.nike", include_nested: true }. ids: { asset_ids: ["abc..."] }. diff: { set_a: {...}, set_b: {...}, mode: "only_in_a" }.
dry_runbooleanOptionalIf true, simulates execution without side effects

FilterStage

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).

ParameterTypeRequiredDescription
stage_typestringRequiredThe FILTER stage type to execute
configobjectOptionalStage-specific configuration. sort: { by: "created_at", order: "desc" }. limit: { count: 20 }. where: { field: "tool", operator: "eq", value: "midjourney" }.
assetsarrayRequiredArray of asset hashes to filter. Required for non-SELECT stages.
dry_runbooleanOptionalIf true, simulates execution without side effects

TransformStage

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.

ParameterTypeRequiredDescription
stage_typestringRequiredThe TRANSFORM stage type to execute
configobjectOptionalStage-specific configuration. set_tag: { tags: ["approved"] }. enrich: { operations: ["auto_tag"] }. set_field: { field: "status", value: "reviewed" }.
assetsarrayRequiredArray of asset hashes to transform
dry_runbooleanOptionalIf true, simulates execution without side effects

ActionStage

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.

ParameterTypeRequiredDescription
stage_typestringRequiredThe ACTION stage type to execute
configobjectOptionalStage-specific configuration. add_to_collection: { path: "projects.nike" }. move: { from: "inbox", to: "approved" }. delete: { confirm: true }. archive: { confirm: true }.
assetsarrayRequiredArray of asset hashes to act on
dry_runbooleanOptionalIf true, simulates execution without side effects

OutputStage

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.

ParameterTypeRequiredDescription
stage_typestringRequiredThe OUTPUT stage type to execute
configobjectOptionalStage-specific configuration. export: { preset: "client", confirm: true }. notify: { event_type: "pipeline.completed" }. tee: { action: { type: "add_to_collection", path: "backup" } }.
assetsarrayRequiredArray of asset hashes for output
dry_runbooleanOptionalIf true, simulates execution without side effects

SummarizeStage

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.

ParameterTypeRequiredDescription
stage_typestringRequiredThe SUMMARIZE stage type to execute
configobjectOptionalStage-specific configuration. count: { group_by: "tool" }. group_by: { field: "mime_type" }. stats: { field: "file_size" }. histogram: { field: "created_at" }.
assetsarrayRequiredArray of asset hashes to summarize
dry_runbooleanOptionalIf true, simulates execution without side effects

Automation Rules

Create, list, and trigger automation rules

CreateRule

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).

ParameterTypeRequiredDescription
namestringRequiredRule name (unique per tenant)
descriptionstringOptionalHuman-readable description of what this rule does
trigger_configobjectRequiredTrigger configuration with type discriminator. Event: { type: "event", event_type: "pipeline.completed" }. Schedule: { type: "schedule", cron: "0 9 * * 1" }. Watch: { type: "watch", query: "tag:unreviewed", interval_minutes: 60 }.
rate_limit_configobjectOptionalOptional rate limiting config (e.g., { max_executions_per_hour: 10 })
pipeline_varsobjectOptionalVariables to inject into pipeline context when rule fires
pipeline_definition_hstringOptional40-char hex hash of the saved pipeline to trigger
pipeline_namestringOptionalPipeline name (alternative to pipeline_definition_h). Resolved to hash automatically.

ListRules

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

ParameterTypeRequiredDescription
enabledbooleanOptionalFilter by enabled/disabled status
trigger_typestringOptionalFilter by trigger type
tenant_idstringOptionalTenant UUID (optional - auto-injected from API key auth)

TriggerRule

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.

ParameterTypeRequiredDescription
trigger_typestringRequiredType of trigger to process: schedule (check cron-due rules), watch (check query-based rules), event (dispatch event to matching rules)
event_typestringOptionalEvent type to dispatch (required when trigger_type is "event", e.g., "pipeline.completed")
event_dataobjectOptionalEvent payload data (optional, passed to matching event rules)
tenant_idstringRequiredTenant UUID (required for event dispatch)

Webhooks

Register webhooks for event-driven integrations

RegisterWebhook

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.

ParameterTypeRequiredDescription
namestringRequiredHuman-readable name for the webhook subscription
urlstringRequiredHTTPS endpoint URL to receive webhook events (must be public, no private IPs)
eventsarrayRequiredEvent types to subscribe to (e.g., ["pipeline.completed", "pipeline.failed"])
descriptionstringOptionalOptional description of the webhook purpose
enabledbooleanOptionalWhether the webhook is enabled (default: true)
timeout_msnumberOptionalRequest timeout in milliseconds, 1000-60000 (default: 10000)

Resources (5)

Resources are browsable read-only data that MCP clients can read for context — collection structure, storage quotas, available presets. Unlike tools, resources don't modify state.

List resources with resources/list, read one with resources/read:

{"jsonrpc":"2.0","method":"resources/read","params":{"uri":"numonic://collections"},"id":3}
numonic://collections

Collection Tree

Hierarchical collection structure with names, paths, and asset counts. Useful for understanding how a library is organized before placing assets.

numonic://storage

Storage Usage

Tenant storage: GB used, quota, percentage, over-limit flag. Check before uploading large batches.

numonic://export-presets

Export Presets

Available privacy presets with compliance metadata (EU AI Act, CA SB 942).

numonic://pipeline-templates

Pipeline Templates

System and tenant pipeline templates. Browse before building custom pipelines.

numonic://asset/{asset_h}

Asset Details

Full metadata for a specific asset. Pass the 40-character hex asset hash. (URI template)

Prompts (5)

Guided multi-step workflows that teach agents the canonical way to accomplish common tasks. They return pre-written instructions that chain multiple tool calls together.

Get a prompt with prompts/get:

{"jsonrpc":"2.0","method":"prompts/get","params":{"name":"search-and-curate","arguments":{"query":"tool:midjourney AND tag:approved"}},"id":5}

Search & Curate

search-and-curate

Search for assets, build a curated collection, and publish it.

Workflow: SearchAssets > CreateCollection > AddToCollection > PublishCollection

ArgumentRequiredDescription
queryYesSearch query or grammar expression
collection_nameNoName for the new collection
privacy_presetNoshare, portfolio, client (default), archive

Ingest & Organize

ingest-and-organize

Upload a new asset and file it into the correct collection.

Workflow: StoreAsset > ListCollections > AddToCollection

ArgumentRequiredDescription
filenameYesName of the file being uploaded
mime_typeYesMIME type (e.g., image/png)
collection_pathNoTarget collection path

Export for Client

export-for-client

Export assets with privacy-aware metadata stripping for client delivery.

Workflow: SearchAssets or GetCollectionAssets > ExportAssets

ArgumentRequiredDescription
query_or_collectionYesSearch query or collection hash
presetNoPrivacy preset (default: client)

Audit Tenant Health

audit-tenant-health

Assess storage usage, search index quality, and overall tenant health.

Workflow: GetTenantStorageDetails > GetSearchAnalytics > summarize

Explore Lineage

explore-lineage

Trace a Midjourney asset's complete evolution chain through variations, upscales, and remixes.

Workflow: GetMidjourneyEvolutionChain > GetCreativeSession > synthesize

ArgumentRequiredDescription
asset_hYesAsset hash (40-char hex)
depthNoMaximum chain depth (default: 10)

Error Handling

The MCP server uses standard JSON-RPC 2.0 error codes.

CodeNameMeaning
-32700Parse ErrorMalformed JSON in request body
-32600Invalid RequestMissing jsonrpc or method field
-32601Method Not FoundUnknown method name
-32602Invalid ParamsMissing or invalid parameters
-32603Internal ErrorServer-side exception

HTTP Status Codes

Parse errors and invalid requests return HTTP 400. All other errors (including tool failures) return HTTP 200 with the error in the JSON-RPC response body — per the JSON-RPC specification.

Tool-Level Errors

Tool errors are returned in the result's content array with isError: true:

{"content":[{"type":"text","text":"Error: ..."}],"isError":true}

Protocol Details

ProtocolModel Context Protocol (JSON-RPC 2.0)
TransportStreamable HTTP (POST)
Supported versions2025-03-26 (primary), 2024-11-05 (backwards compatible)
Server nameNumonic-MCP-Server
Server version1.0.0
Tools37
Resources5 (4 static + 1 URI template)
Prompts5 guided workflows

Further Reading

Ready to Connect Your AI Agent?

Get your API key and start managing assets through MCP in minutes. Works with Claude, Cursor, and any MCP-compatible client.