Numonic
Busca, organiza y publica imágenes y videos generados por IA con procedencia y linaje.
Servidor MCP alojado
npx add-mcp 'https://www.numonic.ai/mcp'Se instala en Claude Code, Codex, Cursor y más
Documentación
Referencia del Servidor MCP
Conecta agentes de IA a tu biblioteca de activos digitales mediante Model Context Protocol. 66 herramientas en 13 dominios, 5 recursos y 5 indicaciones guiadas: listas para Claude, ChatGPT, Gemini, Codex, VS Code, Cursor y agentes personalizados construidos con los SDK de MCP. Cada herramienta MCP tiene un equivalente REST en la Referencia de la API REST.
Herramientas
66
Recursos
5
Indicaciones
5
Transporte
HTTP / JSON-RPC 2.0
Endpoint: POST https://www.numonic.ai/mcp
Primeros pasos
¿Nuevo aquí? La guía de inicio rápido para conectar un agente explica ambas formas de conexión: una clave de API u OAuth para clientes que solo aceptan una URL de conector.
- 1
Crear una clave de API
En el panel de Numonic, ve a Configuración → Espacio de trabajo → Agentes conectados y crea una nueva clave. Las claves están disponibles en todos los planes, incluido el gratuito. Tu clave tiene este formato:napi_a1b2c3d4e5f6…— guárdala de forma segura; no se volverá a mostrar. - 2
Conectar tu cliente MCP
El servidor MCP de Numonic acepta conexiones mediante HTTP Streamable (JSON-RPC 2.0 sobre HTTP POST). Consulta Configuración del cliente para saber cómo conectar Claude, ChatGPT, Gemini, Codex, VS Code, Cursor y otros clientes. -
Probar la conexión
Envía una solicitudinitializepara verificar que todo funciona:
Una respuesta correcta devuelve las capacidades del servidor. Luego lista las herramientas concurl -X POST https://www.numonic.ai/mcp \ -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 }'{"method":"tools/list"}.
Configuración del cliente
Las aplicaciones de chat se conectan con OAuth: pegas la URL e inicias sesión en Numonic. Las herramientas de desarrollo usan una clave de API. Después de editar un archivo de configuración, reinicia el cliente.
Aplicaciones: pega la URL e inicia sesión
https://www.numonic.ai/mcp
Tú eliges el espacio de trabajo y los permisos en la página de consentimiento de Numonic. Pasos de conexión OAuth
Claude (aplicación de escritorio y claude.ai)
Configuración → Conectores → Agregar conector personalizado. Pega la URL, luego inicia sesión en Numonic y aprueba el acceso.
No agregues Numonic a claude_desktop_config.json: ese archivo solo inicia servidores locales. Los planes gratuitos permiten un conector personalizado.
ChatGPT
Configuración → Seguridad e inicio de sesión → activa el Modo desarrollador. Luego abre Plugins, selecciona + y crea una aplicación con la URL.
Planes Plus, Pro, Business, Enterprise y Education, en la web.
Gemini app
gemini.google.com → Configuración → Aplicaciones conectadas → Agregar una aplicación personalizada. Ingresa la URL, selecciona Siguiente e inicia sesión.
Solo cuentas personales de Google (no de trabajo o escuela), mayores de 18 años en EE. UU., en inglés, con Keep Activity activado.
Grok
grok.com/connectors → Nuevo conector → Personalizado. Ingresa la URL e inicia sesión.
Le Chat (Mistral)
Conectores → + Agregar conector → Conector MCP personalizado. Nómbralo numonic, ingresa la URL, selecciona Conectar e inicia sesión.
Solo administradores; en los planes Free, Pro y Student, el propietario de la cuenta es el administrador.
Perplexity
Agrega un conector remoto personalizado con la URL y elige OAuth. La autenticación con clave de API usando tu clave napi_ también funciona.
Planes Pro y Enterprise.
Microsoft Copilot Studio
Herramientas de tu agente → Agregar una herramienta → Nueva herramienta → Model Context Protocol. Ingresa la URL y luego elige OAuth 2.0 → Descubrimiento dinámico.
O elige Clave de API → Encabezado, con el nombre de encabezado X-API-Key, y proporciona tu clave napi_.
Herramientas de desarrollo: usa una clave de API
Claude Code (CLI)
Ejecuta este comando en tu terminal.
claude mcp add --transport http numonic https://www.numonic.ai/mcp \
--header "Authorization: Bearer napi_your_key_here"
Codex (CLI y extensión de IDE)
Codex lee la clave de una variable de entorno, así que configúrala donde se ejecute Codex. El servidor se guarda en ~/.codex/config.toml, que la extensión del IDE también lee. Para iniciar sesión con OAuth en su lugar, omite --bearer-token-env-var y ejecuta codex mcp login numonic.
export NUMONIC_API_KEY=napi_your_key_here
codex mcp add numonic --url https://www.numonic.ai/mcp \
--bearer-token-env-var NUMONIC_API_KEY
Gemini CLI
Ejecuta este comando, o agrega el servidor manualmente a ~/.gemini/settings.json (.gemini/settings.json para un solo proyecto) bajo mcpServers. Manualmente, usa httpUrl, no url: Gemini CLI interpreta url como un endpoint SSE.
gemini mcp add --transport http numonic https://www.numonic.ai/mcp \
--header "Authorization: Bearer napi_your_key_here"
VS Code (GitHub Copilot)
Guarda como .vscode/mcp.json en tu espacio de trabajo, o agrégalo a tu configuración MCP de usuario. VS Code solicita la clave cuando el servidor se inicia. Visual Studio 2022 (17.14+) lee los servidores desde .mcp.json en la carpeta de la solución o %USERPROFILE%\.mcp.json; allí, lista solo la url y elige Administrar autenticación para iniciar sesión con OAuth.
{
"inputs": [
{
"type": "promptString",
"id": "numonic-key",
"description": "Numonic API key",
"password": true
}
],
"servers": {
"numonic": {
"type": "http",
"url": "https://www.numonic.ai/mcp",
"headers": {
"Authorization": "Bearer ${input:numonic-key}"
}
}
}
}
Cursor / Devin Desktop (anteriormente Windsurf)
Cursor: agrega a .cursor/mcp.json en tu proyecto, o ~/.cursor/mcp.json para todos los proyectos. Devin Desktop: agrega a ~/.config/devin/mcp_config.json (%APPDATA%\devin\mcp_config.json en Windows).
{
"mcpServers": {
"numonic": {
"url": "https://www.numonic.ai/mcp",
"headers": {
"Authorization": "Bearer napi_your_key_here"
}
}
}
}
Agentes personalizados (SDK)
TypeScript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport }
from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const transport = new StreamableHTTPClientTransport(
new URL('https://www.numonic.ai/mcp'),
{
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
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async with streamablehttp_client(
"https://www.numonic.ai/mcp",
headers={"Authorization": "Bearer napi_your_key_here"},
) as (read_stream, write_stream, _):
async with ClientSession(read_stream, write_stream) as session:
await session.initialize()
tools = await session.list_tools()
print(f"{len(tools.tools)} tools available")
result = await session.call_tool(
"SearchAssets",
arguments={
"query": "tool:midjourney AND tag:approved",
"limit": 10,
},
)
print(result.content)
Autenticación
Qué credencial usar
| Cliente | Credencial | Notas |
|---|---|---|
| Aplicaciones conectoras: Claude, ChatGPT, Gemini, Grok, Le Chat, Perplexity, Copilot Studio | OAuth 2.1 (código de autorización + PKCE) | El cliente descubre el servidor de autorización desde el endpoint, se registra y te envía a una página de consentimiento de Numonic. Allí eliges el espacio de trabajo y los permisos. No hay clave que pegar. |
| Claude Code, Codex, Gemini CLI, VS Code, Cursor, Devin Desktop (anteriormente Windsurf), scripts y agentes personalizados | Clave de API (napi_...) en un encabezado | Crea la clave en Configuración → Espacio de trabajo → Agentes conectados y envíala como se muestra en Configuración del cliente. |
| Cualquier cosa que use un token de sesión de inicio de sesión de Numonic o Supabase | No aceptado | Un token de sesión o acceso de iniciar sesión en Numonic se rechaza con 401. Usa una clave de API o conéctate mediante OAuth. |
Permisos de conexión OAuth
En la página de consentimiento otorgas a una conexión algunos de los siguientes permisos de Numonic. Son independientes de los alcances OAuth que solicita el cliente (solo identidad, como openid). Una conexión actúa como su propio agente, no como tú, y puedes desconectarla en cualquier momento en Configuración → Espacio de trabajo → Conectores OAuth. Reconectar un conector reemplaza su conexión anterior.
| read | Ver activos, colecciones y sus detalles |
|---|---|
| search | Buscar en tu biblioteca |
| write | Agregar y actualizar activos, etiquetas y colecciones |
| export | Exportar y publicar activos |
admin (ejecutar pipelines, registrar webhooks) no se puede otorgar a una conexión OAuth. Usa una clave de API dedicada para eso.
Implementación gradual: las conexiones OAuth pueden registrarse e iniciar sesión hoy, pero las llamadas a herramientas desde una conexión OAuth se rechazan hasta que se implementen los permisos por conexión. Hasta entonces, usa una clave de API para el acceso a herramientas.
Claves de API
Todas las claves de API deben comenzar con el prefijo napi_. Las claves se almacenan con hash SHA-256 en el servidor: Numonic nunca guarda tu clave en texto plano.
| Método | Encabezado | Nota |
|---|---|---|
| Token Bearer | Authorization: Bearer napi_... | Requerido por la mayoría de los clientes MCP |
| Encabezado de clave de API | X-API-Key: napi_... | Preferido para HTTP directo |
| Encabezado heredado | api-key: napi_... | Compatibilidad hacia atrás |
Acceso multiinquilino
Si tu clave de API tiene acceso a varios inquilinos, pasa X-Tenant-ID para seleccionar en cuál operar. Si se omite, se usa el inquilino predeterminado de la clave.
Herramientas (66)
Operaciones atómicas que tu agente puede llamar mediante tools/call. Cada herramienta acepta un objeto de argumentos JSON y devuelve resultados estructurados.
Ingestión de activos1 herramienta
Almacena e ingiere activos en Numonic
StoreAsset
herramienta · ingestión de activos
Almacena un activo (archivo) en Numonic con metadatos y linaje. Proporciona EXACTAMENTE UNO de: bytes en base64 (asset_data_base64), una referencia a un objeto precargado (asset_storage_ref) o una URL HTTPS que la Edge Function obtendrá del lado del servidor (asset_data_url). El canal de URL solo acepta hosts en lista de permitidos (configurado por implementación mediante MCP_URL_INGEST_ALLOWLIST; predeterminado: URLs firmadas de Supabase + Comfy Cloud + CDN de Midjourney + Civitai + S3 administrado por Numonic). Límite de tamaño predeterminado 100 MB (MCP_URL_INGEST_MAX_BYTES); tiempo de espera de obtención predeterminado 30 s (anulable por llamada mediante timeout_seconds, máximo 300). Códigos de error distintos: URL_EXPIRED, URL_FORBIDDEN_HOST, URL_TOO_LARGE, URL_FETCH_TIMEOUT, URL_CONTENT_TYPE_MISMATCH. El linaje lo determina el servidor: después de la carga, Numonic extrae el prompt, el flujo de trabajo y los modelos incrustados en el archivo (p. ej., metadatos PNG/MP4 de ComfyUI) y GetAssetDetails los informa con provenance.lineage_source. prompt_metadata es OPCIONAL: omítelo cuando no sepas cómo se creó el activo (nunca inventes un prompt o hash de agente); un valor vacío o "none" afirmado nunca anula lo que encuentre la extracción. IMPORTANTE para archivos adjuntos en chat: los conectores MCP en modo desarrollador no reciben de forma confiable una referencia de archivo para un archivo adjunto directamente en el chat (la hidratación openai/fileParams del SDK de OpenAI Apps está documentada para aplicaciones de directorio de Apps SDK de primera parte y no está confirmada para conectores personalizados en modo desarrollador; consulta GitLab #2807). Si el usuario adjunta una imagen/archivo en el chat y te pide almacenarlo, NO vuelvas a codificar un adjunto grande como asset_data_base64 tú mismo: una recodificación en línea grande puede tardar minutos y cancelarse. Pide al usuario una URL para pasar mediante asset_data_url en su lugar, o usa asset_storage_ref si el archivo ya se cargó a una URL firmada emitida por Numonic.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | opcional | ID de inquilino (opcional: se inyecta automáticamente desde la autenticación con clave de API; omítelo para detección automática de inquilino) |
| filename | string | requerido | Nombre de archivo original (no vacío) |
| mime_type | string | requerido | Tipo MIME del activo (p. ej., 'image/png', 'text/plain') |
| asset_data_base64 | string | opcional | Bytes del activo codificados en base64 para activos pequeños. Proporciona esto O asset_storage_ref. |
| asset_data_url | string ·uri | opcional | URL HTTPS que la Edge Function obtendrá del lado del servidor. Solo hosts en lista de permitidos. Mutuamente excluyente con asset_data_base64 / asset_storage_ref. Devuelve códigos de error dedicados (URL_EXPIRED / URL_FORBIDDEN_HOST / URL_TOO_LARGE / URL_FETCH_TIMEOUT / URL_CONTENT_TYPE_MISMATCH). |
| allow_content_type_mismatch | boolean | opcional | Cuando se usa asset_data_url, acepta respuestas cuyo Content-Type no coincida con mime_type. Predeterminado: true porque Comfy Cloud sirve PNG como application/octet-stream. |
| timeout_seconds | integer | opcional | Tiempo de espera de obtención por llamada para asset_data_url (5–300 s). Predeterminado: 30. |
| asset_storage_ref | object | opcional | Referencia a datos de activo ya cargados mediante URL firmada. Mutuamente excluyente con asset_data_base64 / asset_data_url. |
| prompt_metadata | object | opcional | Afirmación OPCIONAL del cliente sobre cómo se generó este activo (prompt + agente que respondió). Omítelo si no lo sabes; el servidor extrae el linaje del archivo almacenado y los datos extraídos siempre ganan sobre una afirmación vacía o "none". |
| asset_metadata | object | opcional | Metadatos descriptivos opcionales para el activo. |
| tags | string[] | opcional | Matriz opcional de nombres de etiquetas para aplicar al activo. |
| collection_h | string | opcional | Hash de colección opcional (SHA-1) para agregar este activo inmediatamente al crearlo. |
| parent_asset_h | string | opcional | Hash de activo opcional (SHA-1) de un activo padre si esto es una versión o derivación. |
Descubrimiento de activos3 herramientas
Recupera activos individuales, URLs públicas y sesiones creativas
GetMidjourneyEvolutionChain
herramienta · descubrimiento de activos
Recupera la cadena de evolución (linaje padre→hijo) de un activo de Midjourney, mostrando cómo evolucionó mediante variaciones y ampliaciones.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| asset_id | string | requerido | El Hash de activo (SHA-1) del activo para obtener la cadena de evolución |
| max_depth | number | opcional | Profundidad máxima a recorrer (predeterminado: 10, máximo: 50) |
GetCreativeSession
herramienta · descubrimiento de activos
Descubre todos los activos de Midjourney creados dentro de una ventana de tiempo de un activo dado, agrupados por proximidad temporal para formar una "sesión creativa".
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| asset_id | string | requerido | El Hash del Asset (SHA-1) del asset para el cual encontrar la sesión |
| time_window | string | opcional | Ventana de tiempo para el descubrimiento de sesiones (p. ej., "2 horas", "30 minutos", "1 día") |
GetAssetPublicUrl
tool · descubrimiento de assets
Búsqueda inversa: determina si un asset está en CUALQUIER colección publicada y devuelve la URL pública. Devuelve uno de tres estados: (1) El asset SÍ está publicado con public_url, collection_path, preset, published_at; (2) El asset NO está publicado pero está en colecciones: lista las rutas de las colecciones; (3) El asset NO está en ninguna colección: array de colecciones vacío.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | opcional | UUID del tenant (opcional - se inyecta automáticamente desde la autenticación por API key) |
| asset_h | string | requerido | Hash del asset (SHA-1, 40 caracteres hexadecimales) a buscar |
Annotations4 tools
Crear, leer, actualizar y eliminar anotaciones de assets
CreateAnnotation
tool · anotaciones
Crea una nueva anotación en un nodo de workflow de ComfyUI con registro de auditoría completo.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| workflow_node_id | string | requerido | Identificador de nodo de workflow hexadecimal de 40 caracteres |
| content | string | requerido | Contenido de texto de la anotación (1-10000 caracteres) |
| content_type | string | opcional | Tipo de formato de contenido enum: text · markdown · json |
| visibility | string | opcional | Nivel de visibilidad: private (solo autor), team (tenant), public (todos) enum: private · team · public |
GetAnnotations
tool · anotaciones
Recupera todas las anotaciones para un nodo de workflow de ComfyUI específico con información del autor.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| workflow_node_id | string | requerido | Identificador de nodo de workflow hexadecimal de 40 caracteres |
| include_resolved | boolean | opcional | Incluir anotaciones resueltas en los resultados (predeterminado: false) |
UpdateAnnotation
tool · anotaciones
Actualiza una anotación existente creando una nueva versión mediante cadena de sustitución (patrón de efectividad).
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| annotation_id | string | requerido | Identificador de anotación hexadecimal de 40 caracteres |
| content | string | opcional | Contenido de anotación actualizado (opcional) |
| visibility | string | opcional | Nivel de visibilidad actualizado (opcional) enum: private · team · public |
DeleteAnnotation
tool · anotaciones
Elimina (eliminación suave) una anotación: la marca como eliminada sin eliminar datos.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| annotation_id | string | requerido | Identificador de anotación hexadecimal de 40 caracteres |
Publishing3 tools
Publicar colecciones y recuperar URLs de acceso público
PublishCollection
tool · publicación
Publica una colección con presets de privacidad y publicación especificados, haciendo que los assets sean accesibles públicamente. Aplica las reglas de eliminación de metadatos ADR-057 y genera URLs públicas.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| collection_h | string | requerido | Hash de la colección (SHA-1, 40 caracteres hexadecimales) a publicar |
| privacy_preset | string | opcional | Preset de privacidad para eliminación de metadatos (ADR-057): share (elimina workflow/modelos/GPS), portfolio (predeterminado, conserva atribución), client (entrega comercial), archive (conserva todos los metadatos) enum: share · portfolio · client · archive |
| publish_preset | string | opcional | Preset de optimización de imagen: web-standard (predeterminado), high-quality, thumbnail enum: web-standard · high-quality · thumbnail |
UnpublishCollection
tool · publicación
Elimina una colección del acceso público. Los assets publicados se marcan como no publicados y se eliminan del almacenamiento público.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| collection_h | string | requerido | Hash de la colección (SHA-1, 40 caracteres hexadecimales) para dejar de publicar |
GetCollectionPublicUrls
tool · publicación
Obtiene el estado de publicación y las URLs públicas de todos los assets de una colección. Devuelve si la colección está publicada, los metadatos de publicación y las URLs de cada asset publicado.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| collection_h | string | requerido | Hash de la colección (SHA-1, 40 caracteres hexadecimales) para obtener las URLs públicas |
Export2 tools
Exportar assets usando presets configurables
ExportAssets
tool · exportación
No disponible aún: la exportación de archivos a través de MCP no produce ningún archivo, por lo que esta herramienta valida su entrada y devuelve un error EXPORT_UNAVAILABLE. Para compartir imágenes, use PublishCollection, que devuelve un enlace público a copias firmadas; para descargar archivos, use la aplicación Numonic o el endpoint REST POST /api/v1/assets/export.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant de destino para esta operación de exportación |
| asset_hs | string[] | requerido | Array de Hashes de Assets (SHA1) a exportar |
| preset | string | opcional | Preset de exportación: share (redes sociales, máxima privacidad), portfolio (conserva atribución), client (entrega comercial), archive (metadatos completos), custom (definido por el usuario) enum: share · portfolio · client · archive · custom |
| options | object | opcional | Opciones personalizadas (solo cuando el preset es "custom"). Control detallado sobre la eliminación de metadatos. |
| format | string | opcional | Formato de salida (preserve = conservar formato de origen) enum: png · jpeg · webp · preserve |
| export_configuration_h | string | opcional | Heredado: Hash de Configuración de Exportación. Mutuamente excluyente con preset. |
ListExportPresets
tool · exportación
Lista los presets de exportación disponibles con sus opciones predeterminadas. Devuelve las configuraciones de preset utilizadas por las exportaciones conscientes de privacidad en la aplicación Numonic y la API REST (ADR-057).
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant (para presets específicos del tenant si están disponibles) |
Analytics2 tools
Consultar analíticas de búsqueda y métricas de almacenamiento del tenant
GetTenantStorageDetails
tool · analíticas
Recupera detalles de uso de almacenamiento de un tenant, incluidos bytes usados, GB usados, límite de almacenamiento, porcentaje usado y estado de superación del límite. Ayuda a monitorear el consumo de almacenamiento y hacer cumplir las cuotas de almacenamiento.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | opcional | Opcional: UUID del tenant a consultar. Si se omite, usa el tenant_id del contexto de autenticación (tenant del usuario actual). |
GetSearchAnalytics
tool · analíticas
Recupera el resumen de analíticas de búsqueda con evaluación de salud (verde/ámbar/rojo) para monitorear la calidad de búsqueda. Devuelve la tasa de resultados cero, percentiles de latencia (P50/P95/P99), desglose por tipo de consulta y las principales consultas con resultados cero. Umbrales de salud: tasa de resultados cero (<15% green, 15-25% amber, >25% rojo), latencia P95 (<500ms green, 500-1000ms amber, >1000ms rojo).
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| period | integer | opcional | Número de días a agregar (1-90). Predeterminado: 7. |
| tenant_id | string ·uuid | opcional | Opcional: UUID del tenant a consultar. Si se omite, devuelve analíticas para todos los tenants o el tenant del usuario actual. |
Pipelines5 tools
Ejecutar, guardar, listar y ejecutar pipelines de procesamiento reutilizables
ExecutePipeline
tool · pipelines
Ejecuta un pipeline de assets de múltiples etapas. Compone etapas de selección, filtro, transformación, acción, salida y resumen en una sola operación. Use dry_run: true para previsualizar los cambios antes de confirmarlos. Etapas por categoría: SELECT: search, collection, ids, diff (comparación de conjuntos). 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 (consciente de privacidad ADR-057), notify (stub), tee (fan-out de paso). SUMMARIZE: count, group_by, stats, histogram. Las etapas de salida requieren confirm: true y se omiten durante la ejecución en seco. Las etapas de resumen se ejecutan durante la ejecución en seco para proporcionar vistas previas de agregación.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| stages | object[] | requerido | Lista ordenada de etapas del pipeline. Debe comenzar con una etapa de selección (search, collection, ids o diff). |
| dry_run | boolean | opcional | Previsualiza lo que sucedería sin ejecutar mutaciones. Las etapas de transformación/acción muestran efectos secundarios simulados. Las etapas de salida se omiten. Las etapas de resumen se ejecutan para proporcionar vistas previas de agregación. Predeterminado: false. |
| timeout_ms | number | opcional | Tiempo máximo de ejecución en milisegundos (1000-60000). Predeterminado: 30000. |
SavePipeline
tool · pipelines
Crea o actualiza un pipeline guardado con nombre. Proporcione pipeline_definition_h para actualizar un pipeline existente (el versionado SCD Tipo 2 conserva el historial completo de ediciones). Omítalo para crear un pipeline nuevo. Los pipelines se identifican por slug (derivado del nombre) y se almacenan con definiciones completas de etapas.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| name | string | requerido | Nombre del pipeline (se usa para generar un slug seguro para URL). Debe ser único por tenant. |
| stages | object[] | requerido | Definiciones ordenadas de etapas del pipeline (mismo formato que las etapas de ExecutePipeline) |
| description | string | opcional | Descripción legible de qué hace este pipeline |
| default_dry_run | boolean | opcional | Configuración predeterminada de dry_run cuando se ejecuta sin anulación (predeterminado: false) |
| default_timeout_ms | number | opcional | Tiempo de espera predeterminado en ms, 1000-60000 (predeterminado: 30000) |
| tags | string[] | opcional | Etiquetas para organizar pipelines (p. ej., ["weekly", "client-delivery"]) |
| pipeline_definition_h | string | opcional | Hash hexadecimal de 40 caracteres del pipeline existente a actualizar. Omítalo para crear uno nuevo. |
ListPipelines
tool · pipelines
Lista los pipelines guardados para el tenant actual. Devuelve metadatos del pipeline, incluidos nombre, número de etapas, etiquetas y configuraciones de ejecución predeterminadas. Use pipeline_definition_h de los resultados con RunSavedPipeline para ejecutar.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tags | string[] | opcional | Filtrar por etiquetas (p. ej., ["weekly"]) |
RunSavedPipeline
tool · pipelines
Ejecuta un pipeline guardado por ID o nombre. Admite anular default_dry_run y default_timeout_ms en tiempo de ejecución. Devuelve el mismo rastro de ejecución que ExecutePipeline. Proporcione pipeline_definition_h (hexadecimal de 40 caracteres) o pipeline_name (se resuelve automáticamente).
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| pipeline_definition_h | string | opcional | Hash hexadecimal de 40 caracteres del pipeline a ejecutar |
| pipeline_name | string | opcional | Nombre del pipeline (alternativa a pipeline_definition_h). Se resuelve a hash automáticamente. |
| dry_run | boolean | opcional | Anula el default_dry_run guardado. Se usa la configuración guardada del pipeline si no se especifica. |
| timeout_ms | number | opcional | Anula el default_timeout_ms guardado (1000-60000) |
| vars | object | opcional | Inyección de variables en tiempo de ejecución (se fusionan en las variables de contexto del pipeline) |
ListPipelineTemplates
tool · pipelines
Lista las plantillas de pipeline disponibles para el tenant actual. Devuelve plantillas del sistema (disponibles para todos los tenants) más cualquier plantilla específica del tenant. Use pipeline_definition_h de los resultados con POST /api/v1/pipelines/templates para clonar una plantilla en un nuevo pipeline guardado.
Pipeline Stages6 tools
Ejecutar etapas individuales del pipeline (selección, filtro, transformación, etc.)
SelectStage
tool · etapas del pipeline
Ejecuta una sola etapa de pipeline de categoría SELECT. Las etapas SELECT son puntos de entrada que producen un conjunto inicial de assets. Valores de stage_type admitidos: search (consulta de texto), collection (cargar desde ruta de colección), ids (hashes de assets explícitos), diff (diferencia de conjuntos entre dos sub-selecciones).
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| stage_type | string | requerido | El tipo de etapa SELECT a ejecutar enum: search · collection · ids · diff |
| config | object | requerido | Configuración específica de la etapa. 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 | opcional | Si es true, simula la ejecución sin efectos secundarios |
FilterStage
tool · etapas de pipeline
Ejecuta una única etapa de pipeline de la categoría FILTER sobre un conjunto de activos. Valores de stage_type admitidos: where (filtro de campo), sort (ordenar por campo), limit (limitar número de resultados), deduplicate (eliminar duplicados), sample (subconjunto aleatorio).
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| stage_type | string | requerido | El tipo de etapa FILTER a ejecutar enum: where · sort · limit · deduplicate · sample |
| config | object | opcional | Configuración específica de la etapa. sort: { by: "created_at", order: "desc" }. limit: { count: 20 }. where: { field: "tool", operator: "eq", value: "midjourney" }. |
| assets | string[] | requerido | Matriz de hashes de activos a filtrar. Requerido para etapas que no son SELECT. |
| dry_run | boolean | opcional | Si es true, simula la ejecución sin efectos secundarios |
TransformStage
tool · etapas de pipeline
Ejecuta una única etapa de pipeline de la categoría TRANSFORM sobre un conjunto de activos. Modifica metadatos de activos o activa el enriquecimiento con IA. Valores de stage_type admitidos: set_tag, remove_tag, set_field, regex_replace, compute, set_visibility, set_owner, enrich, approve.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| stage_type | string | requerido | El tipo de etapa TRANSFORM a ejecutar enum: set_tag · remove_tag · set_field · regex_replace · compute · set_visibility · set_owner · enrich · approve |
| config | object | opcional | Configuración específica de la etapa. set_tag: { tags: ["approved"] }. enrich: { operations: ["auto_tag"] }. set_field: { field: "status", value: "reviewed" }. |
| assets | string[] | requerido | Matriz de hashes de activos a transformar |
| dry_run | boolean | opcional | Si es true, simula la ejecución sin efectos secundarios |
ActionStage
tool · etapas de pipeline
Ejecuta una única etapa de pipeline de la categoría ACTION sobre un conjunto de activos. Realiza operaciones estructurales como mover, eliminar o archivar activos. Valores de stage_type admitidos: add_to_collection, move, delete, archive.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| stage_type | string | requerido | El tipo de etapa ACTION a ejecutar enum: add_to_collection · move · delete · archive |
| config | object | opcional | Configuración específica de la etapa. add_to_collection: { path: "projects.nike" }. move: { from: "inbox", to: "approved" }. delete: { confirm: true }. archive: { confirm: true }. |
| assets | string[] | requerido | Matriz de hashes de activos sobre los que actuar |
| dry_run | boolean | opcional | Si es true, simula la ejecución sin efectos secundarios |
OutputStage
tool · etapas de pipeline
Ejecuta una única etapa de pipeline de la categoría OUTPUT sobre un conjunto de activos. Produce salidas como exportaciones, notificaciones o copias tee. Valores de stage_type admitidos: export, notify, tee.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| stage_type | string | requerido | El tipo de etapa OUTPUT a ejecutar enum: export · notify · tee |
| config | object | opcional | Configuración específica de la etapa. export: { preset: "client", confirm: true }. notify: { event_type: "pipeline.completed" }. tee: { action: { type: "add_to_collection", path: "backup" } }. |
| assets | string[] | requerido | Matriz de hashes de activos para la salida |
| dry_run | boolean | opcional | Si es true, simula la ejecución sin efectos secundarios |
SummarizeStage
tool · etapas de pipeline
Ejecuta una única etapa de pipeline de la categoría SUMMARIZE sobre un conjunto de activos. Produce datos agregados y estadísticas. Valores de stage_type admitidos: count, group_by, stats, histogram.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| stage_type | string | requerido | El tipo de etapa SUMMARIZE a ejecutar enum: count · group_by · stats · histogram |
| config | object | opcional | Configuración específica de la etapa. count: { group_by: "tool" }. group_by: { field: "mime_type" }. stats: { field: "file_size" }. histogram: { field: "created_at" }. |
| assets | string[] | requerido | Matriz de hashes de activos a resumir |
| dry_run | boolean | opcional | Si es true, simula la ejecución sin efectos secundarios |
Automation Rules3 herramientas
Crear, listar y activar reglas de automatización
CreateRule
tool · reglas de automatización
Crea una regla de automatización que activa un pipeline guardado en eventos, horarios o intervalos de vigilancia. Proporcione pipeline_definition_h (hex de 40 caracteres) o pipeline_name (resuelto automáticamente). Tipos de activación: event (se dispara en eventos de activos/pipelines), schedule (basado en cron), watch (verificación periódica de consultas).
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| name | string | requerido | Nombre de la regla (único por tenant) |
| description | string | opcional | Descripción legible de lo que hace esta regla |
| trigger_config | object | requerido | Configuración de activación con discriminador de tipo. 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 | opcional | Configuración opcional de límite de velocidad (p. ej., { max_executions_per_hour: 10 }) |
| pipeline_vars | object | opcional | Variables para inyectar en el contexto del pipeline cuando se activa la regla |
| pipeline_definition_h | string | opcional | Hash hexadecimal de 40 caracteres del pipeline guardado a activar |
| pipeline_name | string | opcional | Nombre del pipeline (alternativa a pipeline_definition_h). Se resuelve automáticamente a hash. |
ListRules
tool · reglas de automatización
Lista las reglas de automatización del tenant actual con filtros opcionales. Devuelve metadatos de la regla, incluidos nombre, tipo de activación, estado habilitado y pipeline vinculado.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| enabled | boolean | opcional | Filtrar por estado habilitado/deshabilitado |
| trigger_type | string | opcional | Filtrar por tipo de activación enum: event · schedule · watch |
| tenant_id | string ·uuid | opcional | UUID del tenant (opcional: se inyecta automáticamente desde la autenticación por clave API) |
TriggerRule
tool · reglas de automatización
Activa manualmente el procesamiento de reglas de automatización. Para schedule/watch: evalúa todas las reglas vencidas del tenant. Para event: envía a las reglas basadas en eventos coincidentes. Devuelve resultados de ejecución para cada regla activada.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| trigger_type | string | requerido | Tipo de activación a procesar: schedule (verificar reglas vencidas por cron), watch (verificar reglas basadas en consultas), event (enviar evento a reglas coincidentes) enum: schedule · watch · event |
| event_type | string | opcional | Tipo de evento a enviar (requerido cuando trigger_type es "event", p. ej., "pipeline.completed") |
| event_data | object | opcional | Datos de carga útil del evento (opcional, se pasan a las reglas de eventos coincidentes) |
| tenant_id | string ·uuid | requerido | UUID del tenant (requerido para el envío de eventos) |
Webhooks1 herramienta
Registrar webhooks para integraciones basadas en eventos
RegisterWebhook
tool · webhooks
Registra una nueva suscripción de webhook para recibir notificaciones de eventos. Devuelve el ID del webhook y el secreto de firma (mostrado una sola vez). Admite eventos: pipeline.completed, pipeline.failed, pipeline.export.completed, test.ping.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| name | string | requerido | Nombre legible para la suscripción de webhook |
| url | string | requerido | URL de endpoint HTTPS para recibir eventos de webhook (debe ser pública, sin IP privadas) |
| events | string[] | requerido | Tipos de eventos a los que suscribirse (p. ej., ["pipeline.completed", "pipeline.failed"]) |
| description | string | opcional | Descripción opcional del propósito del webhook |
| enabled | boolean | opcional | Si el webhook está habilitado (predeterminado: true) |
| timeout_ms | number | opcional | Tiempo de espera de solicitud en milisegundos, 1000-60000 (predeterminado: 10000) |
Uncategorised29 herramientas
Sin categorizar
GetAssetDetails
tool · sin categorizar
Recupera detalles completos de un activo específico por su hash SHA-1, incluido cómo se creó. Responde directamente "¿qué prompt, modelo y flujo de trabajo produjeron esto?" — sin necesidad de descarga: prompts.positive\/prompts.negative\ contienen el prompt, models\[\]\ enumera cada modelo que cargó el flujo de trabajo (nombre, tipo como checkpoint/unet/lora/vae, node_id del cargador), workflow.workflow\_json\ es el grafo completo de ComfyUI (con workflow.tool\_name\, node\_count\, custom\_nodes\), y generation\_parameters\ contiene la configuración del muestreador (model_name, seed, steps, cfg_scale, sampler, scheduler) cuando se leyó de un nodo KSampler estándar; de lo contrario, null (el grafo aún los contiene). provenance.lineage\_source\ indica de dónde proviene ese linaje: 'extracted' (leído por Numonic del archivo almacenado; prompts.source\/workflow.source\ son entonces 'extracted'), 'client_asserted' (solo la afirmación del cargador), o 'unknown' (nada afirmado o encontrado). También devuelve título, descripción, etiquetas, colecciones, procedencia (prompt de creación, activos principales), información de incrustación y derechos de autor. Para registros de Model Library de esos modelos (modelo base, palabras de activación, uso), llame a GetAssetModels. Opcionalmente genera una URL de descarga firmada para el archivo original (válida por 5 minutos).
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| asset_h | string | requerido | El hash del activo (SHA-1) a recuperar |
| include_download_url | boolean | opcional | Si es true, incluye una URL firmada de corta duración para descargar el binario original del activo. Predeterminado: false. |
| include_raw_metadata | boolean | opcional | Si es true, también devuelve la salida bruta del extractor (extracted_metadata) y el workflow_graph nodo por nodo. Estos pueden tener decenas de kilobytes; la respuesta predeterminada ya incluye prompts, modelos y workflow.workflow_json. Predeterminado: false. |
BulkUpdateAssetTags
tool · sin categorizar
Agrega o elimina un conjunto de etiquetas en hasta 100 activos en una sola llamada. Comportamiento por activo: 'add' fusiona en el conjunto de etiquetas existente (sin duplicados); 'remove' elimina las etiquetas listadas de cada activo. Los activos cuyo conjunto de etiquetas no cambia se omiten silenciosamente y se informan como sin cambios en la respuesta. Con ámbito de tenant; usa la misma ruta RLS que PATCH /api/v1/assets/bulk-tag.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| asset_hs | string[] | requerido | Matriz de hashes de activos (SHA-1, hex de 40 caracteres) a los que aplicar la operación. Mínimo 1, máximo 100. |
| operation | string | requerido | 'add' fusiona las etiquetas en el conjunto de etiquetas existente de cada activo (sin duplicados); 'remove' las elimina. Para semántica de reemplazo total en un solo activo, use UpdateAsset. enum: add · remove |
| tags | string[] | requerido | Cadenas de etiquetas a agregar o eliminar. Mínimo 1 carácter, máximo 100 caracteres por etiqueta. Mínimo 1 etiqueta, máximo 50 etiquetas por llamada. |
UpdateAsset
tool · sin categorizar
Actualización parcial de los metadatos escalares de un solo activo: descripción, título y/o etiquetas. La actualización de etiquetas en esta herramienta REEMPLAZA todo el conjunto de etiquetas existente; para operaciones incrementales de agregar/eliminar en múltiples activos, use BulkUpdateAssetTags. Se debe proporcionar al menos uno de descripción, título o etiquetas. Con ámbito de tenant; usa la misma ruta RLS que PATCH /api/v1/assets/[assetH].
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| asset_h | string | requerido | Hash del activo (SHA-1, hex de 40 caracteres) del activo a actualizar. |
| description | string | opcional | Nueva descripción opcional del activo (máx. 5000 caracteres). Reemplaza cualquier descripción existente textualmente. |
| title | string | opcional | Nuevo título opcional del activo (máx. 500 caracteres). |
| tags | string[] | opcional | Nuevo conjunto de etiquetas opcional. REEMPLAZA todo el conjunto de etiquetas existente. Para agregar/eliminar de forma incremental, use BulkUpdateAssetTags. Mín. 0 etiquetas, máx. 500. Cada etiqueta de 1 a 100 caracteres. |
ExportCollectionAsPdf
herramienta · sin categorizar
Exporta una colección como documento PDF. Devuelve el PDF como una cadena codificada en base64 junto con el recuento de páginas y metadatos de tiempo de procesamiento. La API web maneja el diseño, la paginación y la eliminación opcional de marcas de agua.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| collection_h | string | requerido | Hash de la colección (SHA-1, 40 caracteres hex) a exportar |
| remove_watermark | boolean | opcional | Si se debe eliminar la marca de agua de Numonic del PDF exportado. Predeterminado: false. |
AddTextCardToCollection
herramienta · sin categorizar
Agrega una tarjeta de texto enriquecido (diapositiva) a una colección. Las tarjetas de texto se renderizan como diapositivas completas en exportaciones PDF y pueden contener un encabezado, texto del cuerpo, viñetas y una nota destacada de acento. Admite fondos oscuros, degradados y claros con color de acento hex opcional.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| collection_h | string | requerido | Hash de la colección (SHA-1, 40 caracteres hex) |
| heading | string | opcional | Texto del encabezado de la tarjeta |
| heading_size | string | opcional | Tamaño del encabezado: xl, lg o md enum: xl · lg · md |
| body | string | opcional | Texto del cuerpo de la tarjeta |
| bullets | string[] | opcional | Matriz de cadenas de viñetas |
| accent_text | string | opcional | Texto de nota destacada resaltado |
| background | string | opcional | Estilo de fondo. Predeterminado: dark enum: dark · gradient · light |
| accent_color | string | opcional | Código de color hex para elementos de acento (p. ej., #3B82F6) |
| layout | string | opcional | Estilo de diseño. Predeterminado: centered enum: centered · left-aligned |
| position | integer | opcional | Posición en el orden de la colección (basado en 0) |
SearchModels
herramienta · sin categorizar
Busca en la Biblioteca de Modelos modelos (LoRAs, checkpoints, UNETs, etc.) por nombre, tipo o arquitectura base. Devuelve entidades de modelo con metadatos, no activos. Use GetAssetModels para encontrar activos por modelo.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | opcional | UUID del tenant |
| query | string | opcional | Búsqueda de texto en nombre del modelo, nombre mostrado y descripción. Admite coincidencia parcial. |
| model_type | string | opcional | Filtrar por tipo de modelo: lora, checkpoint, unet, clip, upscaler, controlnet, vae, embedding, ip_adapter, llm, etc. |
| base_model | string | opcional | Filtrar por arquitectura base: sdxl, flux, sd15, sd3, sd35, pony, illustrious, noobai, hunyuan, etc. |
| limit | integer | opcional | Máximo de resultados a devolver (predeterminado: 50) |
| offset | integer | opcional | Desplazamiento para paginación (predeterminado: 0) |
GetModelDetails
herramienta · sin categorizar
Obtiene detalles completos de un modelo específico, incluidos metadatos, historial de versiones, recuento de uso de activos y recuento de vistas previas.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | opcional | UUID del tenant |
| model_hash | string | requerido | Clave hash SHA-1 del modelo (de models_h.model) |
GetAssetModels
herramienta · sin categorizar
Obtiene los registros de la Biblioteca de Modelos para cada modelo utilizado para generar un activo específico (checkpoints, UNETs, LoRAs con pesos, VAEs, CLIP, upscalers), con modelo base, tipo y fuente de detección. Limitado a su tenant: un activo que su tenant no posee no devuelve modelos. Para el prompt y el gráfico de flujo de trabajo de ComfyUI, llame a GetAssetDetails.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | opcional | UUID del tenant |
| asset_hash | string | requerido | Clave hash SHA-1 del activo |
LinkModelToAsset
herramienta · sin categorizar
Vincula manualmente un modelo a un activo (para fuentes que no son ComfyUI donde la detección automática no está disponible).
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | opcional | UUID del tenant |
| model_hash | string | requerido | Clave hash SHA-1 del modelo |
| asset_hash | string | requerido | Clave hash SHA-1 del activo |
| model_weight | number | opcional | Valor strength_model de LoRA (p. ej., 0.75). Nulo para checkpoints. |
| detection_source | string | opcional | Cómo se descubrió este vínculo (predeterminado: manual_tag) |
GetModelVersions
herramienta · sin categorizar
Obtiene el historial de versiones de un modelo, incluidos pasos de entrenamiento, puntuaciones de calidad y marca de recomendado.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| model_hash | string | requerido | Clave hash SHA-1 del modelo |
| include_deleted | boolean | opcional | Incluir versiones eliminadas suavemente (predeterminado: false) |
AddModelVersion
herramienta · sin categorizar
Agrega una versión a un modelo con metadatos de entrenamiento, puntuación de calidad y marca de recomendado.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| model_hash | string | requerido | Clave hash SHA-1 del modelo |
| version_tag | string | requerido | Etiqueta de versión (p. ej., v1.0, v2.0, epoch10) |
| version_notes | string | opcional | Registro de cambios o descripción de esta versión |
| training_steps | integer | opcional | Pasos totales de entrenamiento |
| training_epochs | integer | opcional | Épocas totales de entrenamiento |
| training_config | object | opcional | Hiperparámetros de entrenamiento: {"lr": 0.0001, "optimizer": "AdamW"} |
| quality_score | number | opcional | Calificación de calidad (0-10) |
| is_recommended | boolean | opcional | Marcar como la versión recomendada para este modelo |
| trained_at | string ·date-time | opcional | Cuándo se entrenó esta versión |
CreateExperiment
herramienta · sin categorizar
Crea una colección de experimentos para flujos de trabajo estructurados de comparación de imágenes (evaluación comparativa de modelos, pruebas A/B de prompts, evaluación de estilos). Devuelve el hash de la colección de experimentos.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string | requerido | UUID del tenant |
| display_name | string | requerido | Nombre del experimento legible por humanos |
| description | string | opcional | Descripción del experimento |
| hypothesis | string | opcional | Qué prueba este experimento |
| independent_variable | string | opcional | Qué varía entre ejecuciones (p. ej., "condición del prompt", "modelo", "LoRA") |
| control_variable | string | opcional | Qué se mantiene constante (p. ej., "conjunto de semillas", "resolución") |
| model_name | string | opcional | Modelo de generación principal (p. ej., "FLUX.2 Dev") |
| workflow_name | string | opcional | Flujo de trabajo de generación (p. ej., "txt2img") |
| resolution | string | opcional | Resolución de imagen (p. ej., "1024x1024") |
| domain_context | object | opcional | Metadatos específicos del dominio como JSON (p. ej., {"grammar_version": "v3"}) |
RegisterRun
herramienta · sin categorizar
Agrega un activo a un experimento como ejecución con contexto completo (condición, semilla, prompt, modelo, parámetros de dominio).
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| collection_h | string | requerido | Hash de la colección de experimentos (hex de 40 caracteres) |
| asset_h | string | requerido | Hash del activo a registrar como ejecución (hex de 40 caracteres) |
| condition_id | string | opcional | Valor de la variable independiente para esta ejecución (p. ej., "cond2b", "modelo_A") |
| variant_label | string | opcional | Etiqueta de variante legible por humanos (p. ej., "Prompt compilado") |
| seed | integer | opcional | Semilla de generación |
| prompt_text | string | opcional | Prompt exacto utilizado para la generación |
| model_name | string | opcional | Modelo para esta ejecución específica (anula el nivel de experimento) |
| run_params | object | opcional | Parámetros de ejecución específicos del dominio como JSON |
| outcome_tags | string[] | opcional | Etiquetas de clasificación de resultados (p. ej., ["text_literalization", "best_in_set"]) |
| position | integer | opcional | Posición/orden dentro del experimento |
ScoreRun
herramienta · sin categorizar
Califica una ejecución de experimento en dimensiones definidas por el usuario. Crea una anotación de evaluación. Las dimensiones están definidas por el experimento (p. ej., calidad, adherencia, coherencia).
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| collection_item_h | string | requerido | Hash del elemento de colección para la ejecución a calificar (hex de 40 caracteres) |
| scores | object | requerido | Dimensiones de calificación como pares clave-valor (p. ej., {"quality": 4, "coherence": 5}). Los valores son 1-5. |
| flags | object | opcional | Indicadores booleanos (p. ej., {"prompt_leakage": true, "text_literalization": false}) |
| evaluator_type | string | opcional | Quién/qué realizó la evaluación (predeterminado: "human") enum: human · vlm_assisted · embedding_similarity |
| comments | string | opcional | Comentarios de evaluación de formato libre |
CompareRuns
herramienta · sin categorizar
Crea una comparación A/B por pares entre dos ejecuciones de experimento, registrando qué elemento gana en cada dimensión de calificación.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| collection_h | string | requerido | Hash de la colección de experimentos (hex de 40 caracteres) |
| item_a | string | requerido | Hash del elemento de colección de la primera ejecución (hex de 40 caracteres) |
| item_b | string | requerido | Hash del elemento de colección de la segunda ejecución (hex de 40 caracteres) |
| winners | object | requerido | Mapeo de dimensión a ganador (p. ej., {"quality": "<item_a_hash>", "coherence": "<item_b_hash>"}) |
| evaluator_type | string | opcional | Quién/qué realizó la comparación (predeterminado: "human") enum: human · vlm_assisted · embedding_similarity |
| notes | string | opcional | Notas de comparación |
GetExperimentSummary
herramienta · sin categorizar
Obtiene resultados agregados del experimento: recuento de ejecuciones, desglose por condición, distribución de etiquetas de resultados y recuento de comparaciones.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| collection_h | string | requerido | Hash de la colección de experimentos (hex de 40 caracteres) |
CreatePrompt
herramienta · sin categorizar
Crea un nuevo prompt en la Biblioteca de Prompts. Devuelve el hash del prompt e información de versión.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| prompt_text | string | requerido | Contenido de texto del prompt (requerido) |
| name | string | opcional | Nombre del prompt legible por humanos |
| description | string | opcional | Descripción del prompt |
| target_model | string | opcional | Modelo objetivo (p. ej., midjourney, dall-e, flux) |
| category | string | opcional | Categoría del prompt (p. ej., paisaje, retrato) |
| tags | string[] | opcional | Etiquetas del prompt para organización |
GetPrompt
herramienta · sin categorizar
Obtiene un prompt por ID de hash con historial completo de versiones y evaluaciones.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| prompt_h | string | requerido | Hash del hub de prompts (hex de 40 caracteres) |
SearchPrompts
herramienta · sin categorizar
Busca prompts con filtros opcionales de categoría, target_model y paginación.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| category | string | opcional | Filtrar por categoría |
| target_model | string | opcional | Filtrar por modelo objetivo |
| limit | integer | opcional | Tamaño de página (predeterminado 20, máx. 100) |
| offset | integer | opcional | Desplazamiento de paginación (predeterminado 0) |
RenderPrompt
herramienta · sin categorizar
Renderiza una plantilla de prompt sustituyendo los marcadores de posición {{variable}} con los valores proporcionados.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| prompt_h | string | requerido | Hash del prompt hub (hex de 40 caracteres) |
| variables | object | opcional | Variables de plantilla como pares clave-valor (p. ej., {"subject": "cityscape"}) |
RegisterProspect
tool · sin categorizar
Registrar o actualizar un prospecto de outreach en frío: escribe el hub prospects_h + enlace de alcance del tenant + prospect_profile_s, y opcionalmente prospect_research_s (se escribe cuando está presente cualquier campo de investigación, no solo pain_hypothesis — #2000) y prospect_deal_s (cuando trial_start_date o agreed_price están presentes — #2000). Se requiere al menos uno de email / linkedin_url / profile_url / handle / website (#1997); la precedencia de clave cuando hay más de uno presente es email > linkedin_url > profile_url > handle > website. Solo añade — volver a llamar agrega nuevas filas satélite.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| prospect | object | requerido | Datos del prospecto. Se requiere al menos uno de email / linkedin_url / profile_url / handle / website (validado en el servidor). |
| record_source | string | requerido | Etiqueta de origen, p. ej., "cold-outreach-studios:studios-2026-q2". |
SetProspectOwner
tool · sin categorizar
Asignar o reasignar el propietario de un prospecto (#1999). Solo añade — escribe una nueva fila prospect_owner_s; nunca toca prospect_outreach_touch_s, por lo que la reasignación no reescribe el historial de contactos. Se establece independientemente de prospect_outreach_touch_s.sent_by.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| prospect_h | string | requerido | Hash del hub del prospecto (SHA-1). |
| owner | string | requerido | |
| record_source | string | requerido |
LogOutreachTouch
tool · sin categorizar
Añadir un contacto al registro de salida y avanzar el estado de la secuencia de outreach del prospecto. channel acepta email, linkedin, discord, github, contact_form u other (#1998). Ambas escrituras son solo añadir.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| prospect_h | string | requerido | Hash del hub del prospecto (SHA-1). |
| touch | object | requerido | |
| record_source | string | requerido |
GetProspectState
tool · sin categorizar
Devolver el estado completo del prospecto: perfil más reciente + investigación + estado + supresión, además de todos los contactos y respuestas, y contact_link si se ha producido la transferencia.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| prospect_h | string | requerido | Hash del hub del prospecto (SHA-1). |
SearchProspects
tool · sin categorizar
Filtrar prospectos por campaña, estado actual de la secuencia, puntuación ICP mínima, vertical, subcadena de cuenta o propietario (#1999, coincidencia exacta). Los prospectos suprimidos (suppressed_until en el futuro) se excluyen por defecto. Límite predeterminado 50, máximo 200. Cada fila de resultado incluye el propietario actual (null si no está asignado).
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| filters | object | opcional |
SuppressProspect
tool · sin categorizar
Suprimir un prospecto con un motivo y una fecha de finalización opcional. Marca todas las secuencias activas del prospecto como suprimidas. unsubscribe es SIEMPRE permanente (se ignora cualquier suppressed_until). Para not_interested / wrong_person, omita suppressed_until para una supresión permanente o pase una fecha futura para una finita. not_now requiere suppressed_until (la fecha de reenganche).
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| prospect_h | string | requerido | |
| reason | string | requerido | enum: unsubscribe · wrong_person · not_now · not_interested |
| suppressed_until | string,null ·date | opcional | Fecha ISO futura AAAA-MM-DD cuando se levanta la supresión. Omita (o null) para supresión permanente; requerido para not_now; ignorado para unsubscribe (siempre permanente). |
| record_source | string | requerido |
LogReply
tool · sin categorizar
Registrar una respuesta entrante con la clasificación de triaje de respuestas de cold-outreach-studios. Avanza el estado de la secuencia: positivo → responded, not_now/wrong_person/unsubscribe/not_interested/bounced → suprimido, ooo deja el estado sin cambios. bounced (#1998) es una falla de entrega, distinta de toda clasificación de rechazo. reply.refusal_class (#2000) codifica opcionalmente un rechazo T (tiempo) o P (problema), solo válido junto con una clasificación con forma de rechazo. En respuesta positiva, acuña prospect_to_contact_l para que lead-response v0.2 recoja el contacto ahora cálido.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| prospect_h | string | requerido | |
| reply | object | requerido | |
| record_source | string | requerido |
SearchContacts
tool · sin categorizar
Listar contactos CRM en un pipeline (community | enterprise | investor) con etapa opcional y búsqueda de texto libre. Envuelve get_pipeline_contacts; devuelve el perfil más reciente, la etapa del pipeline, la actividad (last_contacted, next_follow_up), además de campos satélite específicos del pipeline (investor: firm_name, investor_type, investment_amount, round, seis_eis_status). Límite predeterminado 50, máximo 200. tenant_id se inyecta automáticamente desde la autenticación por clave API.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| pipeline | string | requerido | Qué pipeline CRM listar. 'investor' para contactos de recaudación de fondos. enum: community · enterprise · investor |
| stage | string | opcional | Filtro opcional de etapa del pipeline (p. ej., "lead", "engaged", "diligence"). |
| search | string | opcional | Coincidencia opcional de subcadena sin distinción de mayúsculas contra el nombre del contacto y linkedin_url. |
| limit | integer | opcional | |
| offset | integer | opcional |
GetRelationshipSummary
tool · sin categorizar
Una respuesta a "quién es este, quién lo posee, qué sigue y cuándo vence" para un contacto CRM, prospecto u organización (#2637). Resuelve contactos duplicados fusionados al registro canónico, une prospectos transferidos y la organización, concilia el propietario (propietario del prospecto > assigned_to del contacto > asignatario de tarea abierta, todos los candidatos devueltos con owner_conflict), elige la próxima acción con vencimiento más temprano entre tareas abiertas, seguimientos, contactos de outreach activos y fechas de reenganche, y devuelve una lista de actividad en orden cronológico inverso (contactos, respuestas, notas, cambios de etapa, tareas, actualizaciones de acuerdos). Mismos datos que el panel GUI CRM de administración.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| tenant_id | string ·uuid | requerido | UUID del tenant |
| entity_type | string | requerido | A qué hub pertenece entity_id. enum: contact · prospect · organization |
| entity_id | string | requerido | Hash del hub (SHA-1) del contacto, prospecto u organización — p. ej., un contacto de SearchContacts o un prospect_h de SearchProspects. |
| activity_limit | integer | opcional | Máximo de entradas de actividad devueltas (predeterminado 50). |
Recursos(5)
Los recursos son datos de solo lectura navegables que los clientes MCP pueden leer para contexto — estructura de colecciones, cuotas de almacenamiento, ajustes preestablecidos disponibles. A diferencia de las herramientas, los recursos no modifican el estado.
resources/list resources/read:
{"jsonrpc":"2.0","method":"resources/read","params":{"uri":"numonic://collections"},"id":3}
numonic://storage
Uso de almacenamiento
recurso
Almacenamiento del tenant: GB usados, cuota, porcentaje, indicador de exceso de límite. Verifique antes de cargar lotes grandes.
numonic://export-presets
Ajustes preestablecidos de exportación
recurso
Ajustes preestablecidos de privacidad disponibles con metadatos de cumplimiento (EU AI Act, CA SB 942).
numonic://pipeline-templates
Plantillas de pipeline
recurso
Plantillas de pipeline del sistema y del tenant. Navegue antes de construir pipelines personalizados.
numonic://asset/{asset_h}
Detalles de activo
recurso · plantilla
Metadatos completos para un activo específico. Pase el hash de activo hexadecimal de 40 caracteres. (Plantilla de URI)
Prompts(5)
Flujos de trabajo guiados de múltiples pasos que enseñan a los agentes la forma canónica de completar tareas comunes. Devuelven instrucciones preescritas que encadenan múltiples llamadas a herramientas.
prompts/get:
{"jsonrpc":"2.0","method":"prompts/get","params":{"name":"search-and-curate","arguments":{"query":"tool:midjourney AND tag:approved"}},"id":5}
Ingestar y organizar
Prompt ingest-and-organize
Subir un nuevo activo y archivarlo en la colección correcta.
Flujo de trabajo: StoreAsset → ListCollections → AddToCollection
| Argumento | Requerido | Descripción |
|---|---|---|
| filename | requerido | Nombre del archivo que se sube |
| mime_type | requerido | Tipo MIME (p. ej., image/png) |
| collection_path | opcional | Ruta de colección de destino |
Exportar para cliente
Prompt export-for-client
Exportar activos con eliminación de metadatos consciente de la privacidad para entrega al cliente.
Flujo de trabajo: SearchAssets o GetCollectionAssets → ExportAssets
| Argumento | Requerido | Descripción |
|---|---|---|
| query_or_collection | requerido | Consulta de búsqueda o hash de colección |
| preset | opcional | Ajuste preestablecido de privacidad (predeterminado: client) |
Auditar salud del tenant
Prompt audit-tenant-health
Evaluar uso de almacenamiento, calidad del índice de búsqueda y salud general del tenant.
Flujo de trabajo: GetTenantStorageDetails → GetSearchAnalytics → resumir
Explorar linaje
Prompt explore-lineage
Rastrear la cadena de evolución completa de un activo de Midjourney a través de variaciones, ampliaciones y remezclas.
Flujo de trabajo: GetMidjourneyEvolutionChain → GetCreativeSession → sintetizar
| Argumento | Requerido | Descripción |
|---|---|---|
| asset_h | requerido | Hash del activo (hex de 40 caracteres) |
| depth | opcional | Profundidad máxima de la cadena (predeterminado: 10) |
Códigos de error
El servidor MCP utiliza códigos de error estándar JSON-RPC 2.0.
| Código | Nombre | Significado |
|---|---|---|
| -32700 | Error de análisis | JSON malformado en el cuerpo de la solicitud |
| -32600 | Solicitud no válida | Falta el campo jsonrpc o method |
| -32601 | Método no encontrado | Nombre de método desconocido |
| -32602 | Parámetros no válidos | Parámetros faltantes o no válidos |
| -32603 | Error interno | Excepción del lado del servidor |
Códigos de estado HTTP
Los errores de análisis y las solicitudes no válidas devuelven HTTP 400. Todos los demás errores (incluidas las fallas de herramientas) devuelven HTTP 200 con el error en el cuerpo de la respuesta JSON-RPC — según la especificación JSON-RPC.
Errores a nivel de herramienta
Los errores de herramientas se devuelven en el arreglo content del resultado con isError: true:
{"content":[{"type":"text","text":"Error: …"}],"isError":true}
Detalles del protocolo
| Protocolo | Model Context Protocol (JSON-RPC 2.0) |
|---|---|
| Transporte | HTTP transmisible (POST) |
| Versiones compatibles | 2025-03-26 (principal), 2024-11-05 (compatible hacia atrás) |
| Nombre del servidor | Numonic-MCP-Server |
| Versión del servidor | 1.0.0 |
| Herramientas | 66 |
| Recursos | 5 (4 estáticos + 1 plantilla de URI) |
| Prompts | 5 flujos de trabajo guiados |
Referencia del servidor MCP: Herramientas, Recursos y Configuración del cliente