Loading...
Loading...
Developer Documentation
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.
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.
MCP is best when your workflow involves an AI agent making decisions about which operations to call — search, organize, export, automate.
Build pipelines that select, filter, transform, and export assets in composable stages — all through structured tool calls.
Export presets enforce EU AI Act and CA SB 942 compliance. Control exactly what metadata is shared publicly.
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.
The Numonic MCP server accepts connections over Streamable HTTP (JSON-RPC 2.0 over HTTP POST):
POST https://<project>.supabase.co/functions/v1/mcp-serverAuthenticate with your API key as a Bearer token or via the X-API-Key header.
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"}.
Copy-paste configuration for popular MCP clients.
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.
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"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"
}
}
}
}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);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)All API keys must start with the napi_ prefix. Keys are SHA-256 hashed server-side — Numonic never stores your raw key.
| Method | Header | Note |
|---|---|---|
| Bearer token | Authorization: Bearer napi_... | Required by most MCP clients |
| API key header | X-API-Key: napi_... | Preferred for direct HTTP |
| Legacy header | api-key: napi_... | Backwards compatibility |
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.
Atomic operations your agent can call via tools/call. Each tool accepts a JSON arguments object and returns structured results.
Store and ingest assets into Numonic
Store an asset (file) in Numonic with metadata. Supports base64-encoded data or storage reference.
| Parameter | Type | Required | Description |
|---|---|---|---|
| asset_data_base64 | string | Optional | Base64-encoded asset data (mutually exclusive with asset_storage_ref) |
| asset_storage_ref | string | Optional | Reference to pre-uploaded asset in storage (mutually exclusive with asset_data_base64) |
| mime_type | string | Required | MIME type of the asset (e.g., image/png) |
| filename | string | Required | Original filename |
| title | string | Optional | Optional asset title |
| description | string | Optional | Optional asset description |
| tags | array | Optional | Optional array of tags |
Search and discover assets using semantic and grammar queries
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant_id | string | Optional | Tenant ID (optional - auto-injected from API key auth, omit for automatic tenant detection) |
| query | string | Optional | Text-based search query with advanced grammar support. Examples: "tool:midjourney AND tag:approved NOT tag:draft", "prompt:"futuristic cityscape"", "created:2024-01-01..2024-12-31". Mutually exclusive with query_vector. |
| search_mode | string | Optional | Search mode for text queries: exact (case-insensitive match), partial (substring), fuzzy (similarity), fulltext (full-text search), boolean (AND/OR/NOT operators), smart (auto-detects best mode). Default: smart |
| query_vector | array | Optional | Embedding vector for semantic search. Dimensions must match the active embedding configuration. Mutually exclusive with query parameter. |
| similar_to_asset_h | string | Optional | Asset hash to find similar assets (alternative to query_vector) |
| filters | object | Optional | Metadata filters (tags, status, mime_type, created_after, created_before) |
| limit | number | Optional | Maximum number of results (default: 20) |
| offset | number | Optional | Pagination offset (default: 0) |
| include_score | boolean | Optional | Include similarity/relevance scores in results (default: true) |
| embedding_configuration_h | string | Optional | Specific embedding configuration to use (required for query_vector or similar_to_asset_h) |
Retrieve individual assets, public URLs, and creative sessions
Retrieve the evolution chain (parent→child lineage) for a Midjourney asset, showing how it evolved through variations and upscales.
| Parameter | Type | Required | Description |
|---|---|---|---|
| asset_id | string | Required | UUID of the asset to get evolution chain for |
| max_depth | number | Optional | Maximum depth to traverse (default: 10, max: 50) |
Discover all Midjourney assets created within a time window of a given asset, grouped by temporal proximity to form a "creative session".
| Parameter | Type | Required | Description |
|---|---|---|---|
| asset_id | string | Required | UUID of the asset to find session for |
| time_window | string | Optional | Time window for session discovery (e.g., "2 hours", "30 minutes", "1 day") |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant_id | string | Optional | Tenant UUID (optional - auto-injected from API key auth) |
| asset_h | string | Required | Asset hash (SHA-1, 40 hex chars) to look up |
Create, read, update, and delete asset annotations
Create a new annotation on a ComfyUI workflow node with full audit trail.
| Parameter | Type | Required | Description |
|---|---|---|---|
| workflow_node_id | string | Required | 40-character hexadecimal workflow node identifier |
| content | string | Required | Annotation text content (1-10000 characters) |
| content_type | string | Optional | Content format type |
| visibility | string | Optional | Visibility level: private (author only), team (tenant), public (all) |
Retrieve all annotations for a specific ComfyUI workflow node with author information.
| Parameter | Type | Required | Description |
|---|---|---|---|
| workflow_node_id | string | Required | 40-character hexadecimal workflow node identifier |
| include_resolved | boolean | Optional | Include resolved annotations in results (default: false) |
Update an existing annotation by creating a new version via supersession chain (effectivity pattern).
| Parameter | Type | Required | Description |
|---|---|---|---|
| annotation_id | string | Required | 40-character hexadecimal annotation identifier |
| content | string | Optional | Updated annotation content (optional) |
| visibility | string | Optional | Updated visibility level (optional) |
Delete (soft delete) an annotation - marks it as deleted without removing data.
| Parameter | Type | Required | Description |
|---|---|---|---|
| annotation_id | string | Required | 40-character hexadecimal annotation identifier |
Organise assets into named, versioned collections
List collections as a hierarchical tree for organizing assets. Supports filtering by parent path and depth.
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant_id | string | Optional | Tenant UUID (optional - auto-injected from API key auth) |
| parent_path | string | Optional | Optional filter to list only descendants of this path (ltree format, e.g., "projects.nike") |
| include_asset_counts | boolean | Optional | Include asset count per collection. Default: true |
| max_depth | number | Optional | Maximum hierarchy depth to return (1-5). Default: 5 |
Create a new collection with optional parent for hierarchy. Collections organize assets into folders with up to 5 levels of nesting.
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant_id | string | Required | UUID of the tenant to create collection in |
| name | string | Required | Collection name (will be normalized to lowercase alphanumeric) |
| parent_path | string | Optional | Parent collection path (ltree format) or null for root collection |
| display_name | string | Optional | Human-friendly display name. Auto-generated from name if not provided |
| description | string | Optional | Optional description for the collection |
| icon | string | Optional | Optional icon identifier for UI |
| color | string | Optional | Optional hex color code (e.g., #3B82F6) |
Add one or more assets to a collection with optional position and role.
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant_id | string | Required | UUID of the tenant |
| collection_path | string | Required | Collection ltree path to add assets to (e.g., "projects.nike") |
| asset_hs | array | Required | Array of asset hashes (SHA-1) to add |
| position | number | Optional | Optional starting position for the first asset. Subsequent assets increment. |
| role | string | Optional | Optional role for all assets (KeyVisual, SupportingElement, ReferenceMaterial, BackgroundAsset, Logo, Variation, Other) |
Get assets in a collection with membership metadata (position, role, added date).
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant_id | string | Required | UUID of the tenant |
| collection_path | string | Required | Collection ltree path to get assets from |
| include_nested | boolean | Optional | Include assets from all descendant collections. Default: false |
| limit | number | Optional | Maximum number of assets to return. Default: 50 |
| offset | number | Optional | Offset for pagination. Default: 0 |
| order_by | string | Optional | Sort order: "position" or "added_at". Default: "position" |
Create a branch or snapshot of a collection. Copies all asset memberships to the new collection. Useful for versioning, client deliveries, or template instances.
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant_id | string | Required | UUID of the tenant |
| source_path | string | Required | Source collection ltree path to branch from |
| new_name | string | Optional | Name for the branch. Auto-generated as "<source>_<type>_<timestamp>" if not provided |
| branch_type | string | Optional | Type of branch: "branch" (editable), "snapshot" (frozen), "template_instance". Default: "branch" |
| snapshot_label | string | Optional | Human-readable label for snapshots (e.g., "v1.0", "Client Review") |
Move a collection (and all descendants) to a new parent location in the hierarchy.
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant_id | string | Required | UUID of the tenant |
| source_path | string | Required | Source collection ltree path to move |
| new_parent_path | string | Optional | New parent ltree path. Null or empty to move to root level. |
Publish collections and retrieve public-access URLs
Publish a collection with specified privacy and publish presets, making assets publicly accessible. Applies ADR-057 metadata stripping rules and generates public URLs.
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant_id | string | Required | UUID of the tenant |
| collection_h | string | Required | Collection hash (SHA-1, 40 hex chars) to publish |
| privacy_preset | string | Optional | Privacy preset for metadata stripping (ADR-057): share (strip workflow/models/GPS), portfolio (default, keeps attribution), client (business delivery), archive (keep all metadata) |
| publish_preset | string | Optional | Image optimization preset: web-standard (default), high-quality, thumbnail |
Remove a collection from public access. Published assets are marked as unpublished and deleted from public storage.
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant_id | string | Required | UUID of the tenant |
| collection_h | string | Required | Collection hash (SHA-1, 40 hex chars) to unpublish |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant_id | string | Required | UUID of the tenant |
| collection_h | string | Required | Collection hash (SHA-1, 40 hex chars) to get public URLs for |
Export assets using configurable presets
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant_id | string | Required | UUID of the target tenant for this export operation |
| asset_hs | array | Required | Array of Asset Hashes (SHA1) to be exported |
| preset | string | Optional | Export preset: share (social media, max privacy), portfolio (keeps attribution), client (business delivery), archive (full metadata), custom (user-defined) |
| options | object | Optional | Custom options (only when preset is "custom"). Fine-grained control over metadata stripping. |
| format | string | Optional | Output format (preserve = keep source format) |
| export_configuration_h | string | Optional | Legacy: Export Configuration Hash. Mutually exclusive with preset. |
List available export presets with their default options and compliance status. Returns preset configurations for privacy-aware asset exports following ADR-057.
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant_id | string | Required | Tenant UUID (for tenant-specific presets if available) |
Query search analytics and tenant storage metrics
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| tenant_id | string | Optional | Optional: UUID of the tenant to query. If omitted, uses the tenant_id from auth context (current user's tenant). |
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).
| Parameter | Type | Required | Description |
|---|---|---|---|
| period | integer | Optional | Number of days to aggregate (1-90). Default: 7. |
| tenant_id | string | Optional | Optional: UUID of the tenant to query. If omitted, returns analytics for all tenants or current user's tenant. |
Execute, save, list, and run reusable processing pipelines
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| stages | array | Required | Ordered list of pipeline stages. Must start with a select stage (search, collection, ids, or diff). |
| dry_run | boolean | Optional | Preview 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_ms | number | Optional | Maximum execution time in milliseconds (1000-60000). Default: 30000. |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Required | Pipeline name (used to generate URL-safe slug). Must be unique per tenant. |
| stages | array | Required | Ordered pipeline stage definitions (same format as ExecutePipeline stages) |
| description | string | Optional | Human-readable description of what this pipeline does |
| default_dry_run | boolean | Optional | Default dry_run setting when run without override (default: false) |
| default_timeout_ms | number | Optional | Default timeout in ms, 1000-60000 (default: 30000) |
| tags | array | Optional | Labels for organizing pipelines (e.g., ["weekly", "client-delivery"]) |
| pipeline_definition_h | string | Optional | 40-char hex hash of existing pipeline to update. Omit to create new. |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| tags | array | Optional | Filter by tags (e.g., ["weekly"]) |
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).
| Parameter | Type | Required | Description |
|---|---|---|---|
| pipeline_definition_h | string | Optional | 40-char hex hash of the pipeline to run |
| pipeline_name | string | Optional | Pipeline name (alternative to pipeline_definition_h). Resolved to hash automatically. |
| dry_run | boolean | Optional | Override the saved default_dry_run. Defaults to pipeline's saved setting. |
| timeout_ms | number | Optional | Override the saved default_timeout_ms (1000-60000) |
| vars | object | Optional | Runtime variable injection (merged into pipeline context vars) |
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 individual pipeline stages (select, filter, transform, etc.)
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).
| Parameter | Type | Required | Description |
|---|---|---|---|
| stage_type | string | Required | The SELECT stage type to execute |
| config | object | Required | Stage-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_run | boolean | Optional | If true, simulates execution without side effects |
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).
| Parameter | Type | Required | Description |
|---|---|---|---|
| stage_type | string | Required | The FILTER stage type to execute |
| config | object | Optional | Stage-specific configuration. sort: { by: "created_at", order: "desc" }. limit: { count: 20 }. where: { field: "tool", operator: "eq", value: "midjourney" }. |
| assets | array | Required | Array of asset hashes to filter. Required for non-SELECT stages. |
| dry_run | boolean | Optional | If true, simulates execution without side effects |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| stage_type | string | Required | The TRANSFORM stage type to execute |
| config | object | Optional | Stage-specific configuration. set_tag: { tags: ["approved"] }. enrich: { operations: ["auto_tag"] }. set_field: { field: "status", value: "reviewed" }. |
| assets | array | Required | Array of asset hashes to transform |
| dry_run | boolean | Optional | If true, simulates execution without side effects |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| stage_type | string | Required | The ACTION stage type to execute |
| config | object | Optional | Stage-specific configuration. add_to_collection: { path: "projects.nike" }. move: { from: "inbox", to: "approved" }. delete: { confirm: true }. archive: { confirm: true }. |
| assets | array | Required | Array of asset hashes to act on |
| dry_run | boolean | Optional | If true, simulates execution without side effects |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| stage_type | string | Required | The OUTPUT stage type to execute |
| config | object | Optional | Stage-specific configuration. export: { preset: "client", confirm: true }. notify: { event_type: "pipeline.completed" }. tee: { action: { type: "add_to_collection", path: "backup" } }. |
| assets | array | Required | Array of asset hashes for output |
| dry_run | boolean | Optional | If true, simulates execution without side effects |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| stage_type | string | Required | The SUMMARIZE stage type to execute |
| config | object | Optional | Stage-specific configuration. count: { group_by: "tool" }. group_by: { field: "mime_type" }. stats: { field: "file_size" }. histogram: { field: "created_at" }. |
| assets | array | Required | Array of asset hashes to summarize |
| dry_run | boolean | Optional | If true, simulates execution without side effects |
Create, list, and trigger automation rules
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).
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Required | Rule name (unique per tenant) |
| description | string | Optional | Human-readable description of what this rule does |
| trigger_config | object | Required | Trigger 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_config | object | Optional | Optional rate limiting config (e.g., { max_executions_per_hour: 10 }) |
| pipeline_vars | object | Optional | Variables to inject into pipeline context when rule fires |
| pipeline_definition_h | string | Optional | 40-char hex hash of the saved pipeline to trigger |
| pipeline_name | string | Optional | Pipeline name (alternative to pipeline_definition_h). Resolved to hash automatically. |
List automation rules for the current tenant with optional filters. Returns rule metadata including name, trigger type, enabled status, and linked pipeline.
| Parameter | Type | Required | Description |
|---|---|---|---|
| enabled | boolean | Optional | Filter by enabled/disabled status |
| trigger_type | string | Optional | Filter by trigger type |
| tenant_id | string | Optional | Tenant UUID (optional - auto-injected from API key auth) |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| trigger_type | string | Required | Type of trigger to process: schedule (check cron-due rules), watch (check query-based rules), event (dispatch event to matching rules) |
| event_type | string | Optional | Event type to dispatch (required when trigger_type is "event", e.g., "pipeline.completed") |
| event_data | object | Optional | Event payload data (optional, passed to matching event rules) |
| tenant_id | string | Required | Tenant UUID (required for event dispatch) |
Register webhooks for event-driven integrations
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Required | Human-readable name for the webhook subscription |
| url | string | Required | HTTPS endpoint URL to receive webhook events (must be public, no private IPs) |
| events | array | Required | Event types to subscribe to (e.g., ["pipeline.completed", "pipeline.failed"]) |
| description | string | Optional | Optional description of the webhook purpose |
| enabled | boolean | Optional | Whether the webhook is enabled (default: true) |
| timeout_ms | number | Optional | Request timeout in milliseconds, 1000-60000 (default: 10000) |
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://collectionsHierarchical collection structure with names, paths, and asset counts. Useful for understanding how a library is organized before placing assets.
numonic://storageTenant storage: GB used, quota, percentage, over-limit flag. Check before uploading large batches.
numonic://export-presetsAvailable privacy presets with compliance metadata (EU AI Act, CA SB 942).
numonic://pipeline-templatesSystem and tenant pipeline templates. Browse before building custom pipelines.
numonic://asset/{asset_h}Full metadata for a specific asset. Pass the 40-character hex asset hash. (URI template)
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-and-curateSearch for assets, build a curated collection, and publish it.
Workflow: SearchAssets > CreateCollection > AddToCollection > PublishCollection
| Argument | Required | Description |
|---|---|---|
| query | Yes | Search query or grammar expression |
| collection_name | No | Name for the new collection |
| privacy_preset | No | share, portfolio, client (default), archive |
ingest-and-organizeUpload a new asset and file it into the correct collection.
Workflow: StoreAsset > ListCollections > AddToCollection
| Argument | Required | Description |
|---|---|---|
| filename | Yes | Name of the file being uploaded |
| mime_type | Yes | MIME type (e.g., image/png) |
| collection_path | No | Target collection path |
export-for-clientExport assets with privacy-aware metadata stripping for client delivery.
Workflow: SearchAssets or GetCollectionAssets > ExportAssets
| Argument | Required | Description |
|---|---|---|
| query_or_collection | Yes | Search query or collection hash |
| preset | No | Privacy preset (default: client) |
audit-tenant-healthAssess storage usage, search index quality, and overall tenant health.
Workflow: GetTenantStorageDetails > GetSearchAnalytics > summarize
explore-lineageTrace a Midjourney asset's complete evolution chain through variations, upscales, and remixes.
Workflow: GetMidjourneyEvolutionChain > GetCreativeSession > synthesize
| Argument | Required | Description |
|---|---|---|
| asset_h | Yes | Asset hash (40-char hex) |
| depth | No | Maximum chain depth (default: 10) |
The MCP server uses standard JSON-RPC 2.0 error codes.
| Code | Name | Meaning |
|---|---|---|
| -32700 | Parse Error | Malformed JSON in request body |
| -32600 | Invalid Request | Missing jsonrpc or method field |
| -32601 | Method Not Found | Unknown method name |
| -32602 | Invalid Params | Missing or invalid parameters |
| -32603 | Internal Error | Server-side exception |
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 errors are returned in the result's content array with isError: true:
{"content":[{"type":"text","text":"Error: ..."}],"isError":true}| Protocol | Model Context Protocol (JSON-RPC 2.0) |
| Transport | Streamable HTTP (POST) |
| Supported versions | 2025-03-26 (primary), 2024-11-05 (backwards compatible) |
| Server name | Numonic-MCP-Server |
| Server version | 1.0.0 |
| Tools | 37 |
| Resources | 5 (4 static + 1 URI template) |
| Prompts | 5 guided workflows |