Numonic
Pesquise, organize e publique imagens e vídeos gerados por IA com procedência e linhagem.
Servidor MCP hospedado
npx add-mcp 'https://www.numonic.ai/mcp'Instala no Claude Code, Codex, Cursor e outros
Documentação
Referência do Servidor MCP
Conecte agentes de IA à sua biblioteca de ativos digitais via Model Context Protocol. 66 ferramentas em 13 domínios, 5 recursos e 5 prompts guiados — prontos para Claude, ChatGPT, Gemini, Codex, VS Code, Cursor e agentes personalizados construídos com os SDKs MCP. Cada ferramenta MCP tem um equivalente REST na Referência da API REST.
Ferramentas
66
Recursos
5
Prompts
5
Transporte
HTTP / JSON-RPC 2.0
Endpoint: POST https://www.numonic.ai/mcp
Primeiros Passos
Novo por aqui? O quickstart connect-an-agent mostra as duas formas de conexão — uma chave de API, ou OAuth para clientes que aceitam apenas uma URL de conector.
- 1
Crie uma chave de API
No painel da Numonic, vá em Configurações → Workspace → Agentes Conectados e crie uma nova chave. As chaves estão disponíveis em todos os planos, incluindo o gratuito. Sua chave se parece comnapi_a1b2c3d4e5f6…— guarde-a com segurança; ela não será exibida novamente. - 2
Conecte seu cliente MCP
O servidor MCP da Numonic aceita conexões via HTTP Streamable (JSON-RPC 2.0 sobre HTTP POST). Consulte Configuração do Cliente para saber como conectar Claude, ChatGPT, Gemini, Codex, VS Code, Cursor e outros clientes. -
Teste a conexão
Envie uma solicitaçãoinitializepara verificar se tudo funciona:
Uma resposta bem-sucedida retorna as capacidades do servidor. Em seguida, liste as ferramentas comcurl -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"}.
Configuração do Cliente
Aplicativos de chat conectam-se com OAuth: você cola a URL e faz login na Numonic. Ferramentas de desenvolvedor usam uma chave de API. Após editar um arquivo de configuração, reinicie o cliente.
Aplicativos: cole a URL e faça login
https://www.numonic.ai/mcp
Você escolhe o workspace e as permissões na página de consentimento da Numonic. Etapas de conexão OAuth
Claude (aplicativo desktop e claude.ai)
Configurações → Conectores → Adicionar conector personalizado. Cole a URL, faça login na Numonic e aprove o acesso.
Não adicione a Numonic ao claude_desktop_config.json: esse arquivo apenas inicia servidores locais. Planos gratuitos permitem um conector personalizado.
ChatGPT
Configurações → Segurança e login → ative o Modo desenvolvedor. Em seguida, abra Plugins, selecione + e crie um aplicativo com a URL.
Planos Plus, Pro, Business, Enterprise e Education, na web.
Aplicativo Gemini
gemini.google.com → Configurações → Aplicativos conectados → Adicionar um aplicativo personalizado. Insira a URL, selecione Avançar e faça login.
Somente contas pessoais do Google (não de trabalho ou escola), maiores de 18 anos nos EUA, em inglês, com Manter atividade ativado.
Grok
grok.com/connectors → Novo conector → Personalizado. Insira a URL e faça login.
Le Chat (Mistral)
Conectores → + Adicionar conector → Conector MCP personalizado. Nomeie-o como numonic, insira a URL, selecione Conectar e faça login.
Somente administradores; nos planos Free, Pro e Student, o proprietário da conta é o administrador.
Perplexity
Adicione um conector remoto personalizado com a URL e escolha OAuth. A autenticação por chave de API com sua chave napi_ também funciona.
Planos Pro e Enterprise.
Microsoft Copilot Studio
Ferramentas do seu agente → Adicionar uma ferramenta → Nova ferramenta → Model Context Protocol. Insira a URL e escolha OAuth 2.0 → Descoberta dinâmica.
Ou escolha Chave de API → Cabeçalho, com o nome do cabeçalho X-API-Key, e forneça sua chave napi_.
Ferramentas de desenvolvedor: use uma chave de API
Claude Code (CLI)
Execute este comando no seu terminal.
claude mcp add --transport http numonic https://www.numonic.ai/mcp \
--header "Authorization: Bearer napi_your_key_here"
Codex (CLI e extensão de IDE)
O Codex lê a chave de uma variável de ambiente, então defina-a onde o Codex é executado. O servidor é salvo em ~/.codex/config.toml, que a extensão de IDE também lê. Para entrar com OAuth em vez disso, omita --bearer-token-env-var e execute 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
Execute este comando, ou adicione o servidor manualmente em ~/.gemini/settings.json (.gemini/settings.json para um único projeto) sob mcpServers. Manualmente, use httpUrl, não url: o Gemini CLI lê url como um endpoint SSE.
gemini mcp add --transport http numonic https://www.numonic.ai/mcp \
--header "Authorization: Bearer napi_your_key_here"
VS Code (GitHub Copilot)
Salve como .vscode/mcp.json no seu workspace, ou adicione-o à sua configuração MCP de usuário. O VS Code solicita a chave quando o servidor inicia. O Visual Studio 2022 (17.14+) lê servidores de .mcp.json na pasta da solução ou %USERPROFILE%\.mcp.json; lá, liste apenas a url e escolha Gerenciar autenticação para entrar com 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: adicione a .cursor/mcp.json no seu projeto, ou ~/.cursor/mcp.json para todos os projetos. Devin Desktop: adicione a ~/.config/devin/mcp_config.json (%APPDATA%\devin\mcp_config.json no Windows).
{
"mcpServers": {
"numonic": {
"url": "https://www.numonic.ai/mcp",
"headers": {
"Authorization": "Bearer napi_your_key_here"
}
}
}
}
Agentes personalizados (SDKs)
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)
Autenticação
Qual credencial usar
| Cliente | Credencial | Observações |
|---|---|---|
| Aplicativos conector: Claude, ChatGPT, Gemini, Grok, Le Chat, Perplexity, Copilot Studio | OAuth 2.1 (código de autorização + PKCE) | O cliente descobre o servidor de autorização a partir do endpoint, registra-se e envia você para uma página de consentimento da Numonic. Você escolhe o workspace e as permissões lá. Sem chave para colar. |
| Claude Code, Codex, Gemini CLI, VS Code, Cursor, Devin Desktop (anteriormente Windsurf), scripts e agentes personalizados | Chave de API (napi_...) em um cabeçalho | Crie a chave em Configurações → Workspace → Agentes Conectados e envie-a conforme mostrado na Configuração do Cliente. |
| Qualquer coisa usando um token de sessão de login da Numonic ou Supabase | Não aceito | Um token de sessão ou acesso de login na Numonic é rejeitado com 401. Use uma chave de API ou conecte-se via OAuth. |
Permissões de conexão OAuth
Na página de consentimento, você concede a uma conexão algumas das seguintes permissões da Numonic. Elas são separadas dos escopos OAuth que o cliente solicita (somente identidade, como openid). Uma conexão atua como seu próprio agente, não como você, e você pode desconectá-la a qualquer momento em Configurações → Workspace → Conectores OAuth. Reconectar um conector substitui sua conexão anterior.
| read | Visualizar ativos, coleções e seus detalhes |
|---|---|
| search | Pesquisar sua biblioteca |
| write | Adicionar e atualizar ativos, tags e coleções |
| export | Exportar e publicar ativos |
admin (executar pipelines, registrar webhooks) não pode ser concedido a uma conexão OAuth. Use uma chave de API dedicada para isso.
Implementação gradual: conexões OAuth podem registrar e entrar hoje, mas chamadas de ferramentas de uma conexão OAuth são recusadas até que as permissões por conexão sejam lançadas. Até lá, use uma chave de API para acesso às ferramentas.
Chaves de API
Todas as chaves de API devem começar com o prefixo napi_. As chaves são hash SHA-256 no servidor — a Numonic nunca armazena sua chave bruta.
| Método | Cabeçalho | Observação |
|---|---|---|
| Token Bearer | Authorization: Bearer napi_... | Exigido pela maioria dos clientes MCP |
| Cabeçalho de chave de API | X-API-Key: napi_... | Preferido para HTTP direto |
| Cabeçalho legado | api-key: napi_... | Compatibilidade retroativa |
Acesso multi-tenant
Se sua chave de API tiver acesso a vários tenants, passe X-Tenant-ID para selecionar em qual tenant operar. Se omitido, o tenant padrão da chave é usado.
Ferramentas (66)
Operações atômicas que seu agente pode chamar via tools/call. Cada ferramenta aceita um objeto de argumentos JSON e retorna resultados estruturados.
Ingestão de Ativos — 1 ferramenta
Armazene e ingira ativos na Numonic
StoreAsset
ferramenta · ingestão de ativos
Armazene um ativo (arquivo) na Numonic com metadados e linhagem. Forneça EXATAMENTE UM de: bytes em base64 (asset_data_base64), uma referência a um objeto pré-carregado (asset_storage_ref), ou uma URL HTTPS que a Edge Function buscará no servidor (asset_data_url). O canal de URL aceita apenas hosts na lista de permissões (configurado por implantação via MCP_URL_INGEST_ALLOWLIST; padrão: URLs assinadas do Supabase + Comfy Cloud + CDN do Midjourney + Civitai + S3 gerenciado pela Numonic). Limite de tamanho padrão de 100 MB (MCP_URL_INGEST_MAX_BYTES); tempo limite de busca padrão de 30s (substituível por chamada via timeout_seconds, máx. 300). Códigos de erro distintos: URL_EXPIRED, URL_FORBIDDEN_HOST, URL_TOO_LARGE, URL_FETCH_TIMEOUT, URL_CONTENT_TYPE_MISMATCH. A linhagem é determinada pelo servidor: após o upload, a Numonic extrai o prompt, o workflow e os modelos incorporados no arquivo (por exemplo, metadados PNG/MP4 do ComfyUI) e o GetAssetDetails os relata com provenance.lineage_source. prompt_metadata é OPCIONAL — omita-o quando você não souber como o ativo foi criado (nunca invente um prompt ou hash de agente); um valor vazio ou "none" afirmado nunca substitui o que a extração encontra. IMPORTANTE para arquivos anexados em chat: conectores MCP em modo desenvolvedor não recebem de forma confiável uma referência de arquivo para um arquivo anexado diretamente no chat (a hidratação openai/fileParams do SDK de Apps da OpenAI é documentada para aplicativos de diretório do SDK de Apps de primeira parte e não é confirmada para conectores personalizados em modo desenvolvedor — veja GitLab #2807). Se o usuário anexar uma imagem/arquivo no chat e pedir para armazená-lo, NÃO re-codifique você mesmo um anexo grande como asset_data_base64 — uma re-codificação inline grande pode levar minutos e ser cancelada. Peça ao usuário uma URL para passar via asset_data_url, ou use asset_storage_ref se o arquivo já foi enviado para uma URL assinada emitida pela Numonic.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | opcional | ID do tenant (opcional — injetado automaticamente da autenticação por chave de API, omita para detecção automática de tenant) |
| filename | string | obrigatório | Nome original do arquivo (não vazio) |
| mime_type | string | obrigatório | Tipo MIME do ativo (ex.: 'image/png', 'text/plain') |
| asset_data_base64 | string | opcional | Bytes do ativo codificados em base64 para ativos pequenos. Forneça isto OU asset_storage_ref. |
| asset_data_url | string ·uri | opcional | URL HTTPS que a Edge Function buscará no servidor. Somente hosts na lista de permissões. Mutuamente exclusivo com asset_data_base64 / asset_storage_ref. Retorna códigos de erro dedicados (URL_EXPIRED / URL_FORBIDDEN_HOST / URL_TOO_LARGE / URL_FETCH_TIMEOUT / URL_CONTENT_TYPE_MISMATCH). |
| allow_content_type_mismatch | boolean | opcional | Quando asset_data_url é usado, aceita respostas cujo Content-Type não corresponde a mime_type. Padrão: true, porque o Comfy Cloud serve PNGs como application/octet-stream. |
| timeout_seconds | integer | opcional | Tempo limite de busca por chamada para asset_data_url (5–300s). Padrão: 30. |
| asset_storage_ref | object | opcional | Referência a dados de ativo já enviados via URL assinada. Mutuamente exclusivo com asset_data_base64 / asset_data_url. |
| prompt_metadata | object | opcional | Afirmação OPCIONAL do cliente sobre como este ativo foi gerado (prompt + agente responsável). Omita se você não souber; o servidor extrai a linhagem do arquivo armazenado e os dados extraídos sempre vencem uma afirmação vazia ou "none". |
| asset_metadata | object | opcional | Metadados descritivos opcionais para o ativo. |
| tags | string[] | opcional | Matriz opcional de nomes de tags para aplicar ao ativo. |
| collection_h | string | opcional | Hash de Coleção opcional (SHA-1) para adicionar este ativo imediatamente na criação. |
| parent_asset_h | string | opcional | Hash de Ativo opcional (SHA-1) de um ativo pai se este for uma versão ou derivação. |
Descoberta de Ativos — 3 ferramentas
Recupere ativos individuais, URLs públicas e sessões criativas
GetMidjourneyEvolutionChain
ferramenta · descoberta de ativos
Recupere a cadeia de evolução (linhagem pai→filho) de um ativo do Midjourney, mostrando como ele evoluiu por variações e upscales.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| asset_id | string | obrigatório | O Hash de Ativo (SHA-1) do ativo para obter a cadeia de evolução |
| max_depth | number | opcional | Profundidade máxima para percorrer (padrão: 10, máx.: 50) |
GetCreativeSession
ferramenta · descoberta de ativos
Descubra todos os ativos do Midjourney criados dentro de uma janela de tempo de um determinado ativo, agrupados por proximidade temporal para formar uma "sessão criativa".
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| asset_id | string | obrigatório | O Hash do Asset (SHA-1) do asset para encontrar a sessão |
| time_window | string | opcional | Janela de tempo para descoberta de sessão (ex.: "2 horas", "30 minutos", "1 dia") |
GetAssetPublicUrl
ferramenta · descoberta de assets
Busca reversa: verifica se um asset está em QUALQUER coleção publicada e retorna a URL pública. Retorna um de três estados: (1) Asset ESTÁ publicado com public_url, collection_path, preset, published_at; (2) Asset NÃO publicado, mas em coleções: lista os caminhos das coleções; (3) Asset NÃO está em nenhuma coleção: array de coleções vazio.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | opcional | UUID do tenant (opcional - injetado automaticamente pela autenticação via API key) |
| asset_h | string | obrigatório | Hash do asset (SHA-1, 40 caracteres hexadecimais) para consultar |
Annotations4 ferramentas
Criar, ler, atualizar e excluir anotações de assets
CreateAnnotation
ferramenta · anotações
Cria uma nova anotação em um nó de workflow do ComfyUI com trilha de auditoria completa.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| workflow_node_id | string | obrigatório | Identificador hexadecimal de 40 caracteres do nó do workflow |
| content | string | obrigatório | Conteúdo do texto da anotação (1-10000 caracteres) |
| content_type | string | opcional | Tipo de formato do conteúdo enum: text · markdown · json |
| visibility | string | opcional | Nível de visibilidade: private (somente autor), team (tenant), public (todos) enum: private · team · public |
GetAnnotations
ferramenta · anotações
Recupera todas as anotações de um nó específico de workflow do ComfyUI com informações do autor.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| workflow_node_id | string | obrigatório | Identificador hexadecimal de 40 caracteres do nó do workflow |
| include_resolved | boolean | opcional | Incluir anotações resolvidas nos resultados (padrão: false) |
UpdateAnnotation
ferramenta · anotações
Atualiza uma anotação existente criando uma nova versão via cadeia de substituição (padrão de efetividade).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| annotation_id | string | obrigatório | Identificador hexadecimal de 40 caracteres da anotação |
| content | string | opcional | Conteúdo atualizado da anotação (opcional) |
| visibility | string | opcional | Nível de visibilidade atualizado (opcional) enum: private · team · public |
DeleteAnnotation
ferramenta · anotações
Exclui (exclusão lógica) uma anotação - marca como excluída sem remover os dados.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| annotation_id | string | obrigatório | Identificador hexadecimal de 40 caracteres da anotação |
Publishing3 ferramentas
Publicar coleções e recuperar URLs de acesso público
PublishCollection
ferramenta · publicação
Publica uma coleção com presets de privacidade e publicação especificados, tornando os assets publicamente acessíveis. Aplica as regras de remoção de metadados ADR-057 e gera URLs públicas.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| collection_h | string | obrigatório | Hash da coleção (SHA-1, 40 caracteres hexadecimais) para publicar |
| privacy_preset | string | opcional | Preset de privacidade para remoção de metadados (ADR-057): share (remove workflow/modelos/GPS), portfolio (padrão, mantém atribuição), client (entrega comercial), archive (mantém todos os metadados) enum: share · portfolio · client · archive |
| publish_preset | string | opcional | Preset de otimização de imagem: web-standard (padrão), high-quality, thumbnail enum: web-standard · high-quality · thumbnail |
UnpublishCollection
ferramenta · publicação
Remove uma coleção do acesso público. Assets publicados são marcados como não publicados e excluídos do armazenamento público.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| collection_h | string | obrigatório | Hash da coleção (SHA-1, 40 caracteres hexadecimais) para despublicar |
GetCollectionPublicUrls
ferramenta · publicação
Obtém o status de publicação e as URLs públicas de todos os assets em uma coleção. Retorna se a coleção está publicada, metadados de publicação e URLs para cada asset publicado.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| collection_h | string | obrigatório | Hash da coleção (SHA-1, 40 caracteres hexadecimais) para obter URLs públicas |
Export2 ferramentas
Exportar assets usando presets configuráveis
ExportAssets
ferramenta · exportação
Ainda não disponível: a exportação de arquivos via MCP não produz arquivo, então esta ferramenta valida sua entrada e retorna um erro EXPORT_UNAVAILABLE. Para compartilhar imagens, use PublishCollection, que retorna um link público para cópias assinadas; para baixar arquivos, use o aplicativo Numonic ou o endpoint REST POST /api/v1/assets/export.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant de destino para esta operação de exportação |
| asset_hs | string[] | obrigatório | Array de Hashes de Assets (SHA1) a serem exportados |
| preset | string | opcional | Preset de exportação: share (mídias sociais, máxima privacidade), portfolio (mantém atribuição), client (entrega comercial), archive (metadados completos), custom (definido pelo usuário) enum: share · portfolio · client · archive · custom |
| options | object | opcional | Opções personalizadas (somente quando preset é "custom"). Controle refinado sobre a remoção de metadados. |
| format | string | opcional | Formato de saída (preserve = manter formato de origem) enum: png · jpeg · webp · preserve |
| export_configuration_h | string | opcional | Legado: Hash de Configuração de Exportação. Mutuamente exclusivo com preset. |
ListExportPresets
ferramenta · exportação
Lista os presets de exportação disponíveis com suas opções padrão. Retorna as configurações de preset usadas pelas exportações com consciência de privacidade no aplicativo Numonic e na API REST (ADR-057).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant (para presets específicos do tenant, se disponíveis) |
Analytics2 ferramentas
Consultar análises de busca e métricas de armazenamento do tenant
GetTenantStorageDetails
ferramenta · análises
Recupera detalhes de uso de armazenamento de um tenant, incluindo bytes usados, GB usados, limite de armazenamento, porcentagem usada e status de excedente de limite. Ajuda a monitorar o consumo de armazenamento e aplicar cotas de armazenamento.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | opcional | Opcional: UUID do tenant para consultar. Se omitido, usa o tenant_id do contexto de autenticação (tenant do usuário atual). |
GetSearchAnalytics
ferramenta · análises
Recupera o resumo de análises de busca com avaliação de saúde (verde/âmbar/vermelho) para monitorar a qualidade da busca. Retorna taxa de resultados zero, percentis de latência (P50/P95/P99), detalhamento por tipo de consulta e principais consultas com resultado zero. Limites de saúde: taxa de resultados zero (<15% green, 15-25% amber, >25% vermelho), latência P95 (<500ms green, 500-1000ms amber, >1000ms vermelho).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| period | integer | opcional | Número de dias para agregar (1-90). Padrão: 7. |
| tenant_id | string ·uuid | opcional | Opcional: UUID do tenant para consultar. Se omitido, retorna análises para todos os tenants ou para o tenant do usuário atual. |
Pipelines5 ferramentas
Executar, salvar, listar e executar pipelines de processamento reutilizáveis
ExecutePipeline
ferramenta · pipelines
Executa um pipeline de assets em múltiplos estágios. Compõe estágios de seleção, filtro, transformação, ação, saída e resumo em uma única operação. Use dry_run: true para visualizar as alterações antes de confirmar. Estágios por categoria: SELECT: search, collection, ids, diff (comparação 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 (ADR-057 com consciência de privacidade), notify (stub), tee (fan-out de passagem). SUMMARIZE: count, group_by, stats, histogram. Estágios de saída exigem confirm: true e são ignorados durante dry-run. Estágios de resumo são executados durante dry-run para fornecer prévias de agregação.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| stages | object[] | obrigatório | Lista ordenada de estágios do pipeline. Deve começar com um estágio de seleção (search, collection, ids ou diff). |
| dry_run | boolean | opcional | Visualiza o que aconteceria sem executar mutações. Estágios de transformação/ação mostram efeitos colaterais simulados. Estágios de saída são ignorados. Estágios de resumo são executados para fornecer prévias de agregação. Padrão: false. |
| timeout_ms | number | opcional | Tempo máximo de execução em milissegundos (1000-60000). Padrão: 30000. |
SavePipeline
ferramenta · pipelines
Cria ou atualiza um pipeline salvo nomeado. Forneça pipeline_definition_h para atualizar um pipeline existente (versionamento SCD Type 2 preserva o histórico completo de edições). Omita para criar um novo pipeline. Pipelines são identificados por slug (derivado do nome) e armazenados com definições completas de estágios.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| name | string | obrigatório | Nome do pipeline (usado para gerar slug seguro para URL). Deve ser único por tenant. |
| stages | object[] | obrigatório | Definições ordenadas dos estágios do pipeline (mesmo formato dos estágios do ExecutePipeline) |
| description | string | opcional | Descrição legível do que este pipeline faz |
| default_dry_run | boolean | opcional | Configuração padrão de dry_run quando executado sem substituição (padrão: false) |
| default_timeout_ms | number | opcional | Timeout padrão em ms, 1000-60000 (padrão: 30000) |
| tags | string[] | opcional | Rótulos para organizar pipelines (ex.: ["weekly", "client-delivery"]) |
| pipeline_definition_h | string | opcional | Hash hexadecimal de 40 caracteres do pipeline existente para atualizar. Omita para criar novo. |
ListPipelines
ferramenta · pipelines
Lista pipelines salvos para o tenant atual. Retorna metadados do pipeline, incluindo nome, contagem de estágios, tags e configurações padrão de execução. Use pipeline_definition_h dos resultados com RunSavedPipeline para executar.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tags | string[] | opcional | Filtrar por tags (ex.: ["weekly"]) |
RunSavedPipeline
ferramenta · pipelines
Executa um pipeline salvo por ID ou nome. Suporta substituição de default_dry_run e default_timeout_ms no momento da execução. Retorna o mesmo rastreamento de execução do ExecutePipeline. Forneça pipeline_definition_h (hex de 40 caracteres) ou pipeline_name (resolvido automaticamente).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| pipeline_definition_h | string | opcional | Hash hexadecimal de 40 caracteres do pipeline a ser executado |
| pipeline_name | string | opcional | Nome do pipeline (alternativa ao pipeline_definition_h). Resolvido para hash automaticamente. |
| dry_run | boolean | opcional | Substitui o default_dry_run salvo. Padrão: configuração salva do pipeline. |
| timeout_ms | number | opcional | Substitui o default_timeout_ms salvo (1000-60000) |
| vars | object | opcional | Injeção de variáveis em tempo de execução (mescladas nas variáveis de contexto do pipeline) |
ListPipelineTemplates
ferramenta · pipelines
Lista os modelos de pipeline disponíveis para o tenant atual. Retorna modelos do sistema (disponíveis para todos os tenants) além de quaisquer modelos específicos do tenant. Use o pipeline_definition_h dos resultados com POST /api/v1/pipelines/templates para clonar um modelo em um novo pipeline salvo.
Pipeline Stages6 ferramentas
Executar estágios individuais de pipeline (seleção, filtro, transformação, etc.)
SelectStage
ferramenta · estágios de pipeline
Executa um único estágio de pipeline da categoria SELECT. Estágios SELECT são pontos de entrada que produzem um conjunto inicial de assets. Valores suportados de stage_type: search (consulta de texto), collection (carregar do caminho da coleção), ids (hashes explícitos de assets), diff (diferença de conjuntos entre duas sub-seleções).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| stage_type | string | obrigatório | O tipo de estágio SELECT a executar enum: search · collection · ids · diff |
| config | object | obrigatório | Configuração específica do estágio. 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 | Se verdadeiro, simula a execução sem efeitos colaterais |
FilterStage
tool · estágios de pipeline
Executa um único estágio de pipeline da categoria FILTER em um conjunto de ativos. Valores suportados para stage_type: where (filtro de campo), sort (ordenar por campo), limit (limitar contagem de resultados), deduplicate (remover duplicatas), sample (subconjunto aleatório).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| stage_type | string | obrigatório | O tipo de estágio FILTER a executar enum: where · sort · limit · deduplicate · sample |
| config | object | opcional | Configuração específica do estágio. sort: { by: "created_at", order: "desc" }. limit: { count: 20 }. where: { field: "tool", operator: "eq", value: "midjourney" }. |
| assets | string[] | obrigatório | Matriz de hashes de ativos para filtrar. Obrigatório para estágios não-SELECT. |
| dry_run | boolean | opcional | Se verdadeiro, simula a execução sem efeitos colaterais |
TransformStage
tool · estágios de pipeline
Executa um único estágio de pipeline da categoria TRANSFORM em um conjunto de ativos. Modifica metadados de ativos ou aciona enriquecimento por IA. Valores suportados para stage_type: set_tag, remove_tag, set_field, regex_replace, compute, set_visibility, set_owner, enrich, approve.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| stage_type | string | obrigatório | O tipo de estágio TRANSFORM a executar enum: set_tag · remove_tag · set_field · regex_replace · compute · set_visibility · set_owner · enrich · approve |
| config | object | opcional | Configuração específica do estágio. set_tag: { tags: ["approved"] }. enrich: { operations: ["auto_tag"] }. set_field: { field: "status", value: "reviewed" }. |
| assets | string[] | obrigatório | Matriz de hashes de ativos para transformar |
| dry_run | boolean | opcional | Se verdadeiro, simula a execução sem efeitos colaterais |
ActionStage
tool · estágios de pipeline
Executa um único estágio de pipeline da categoria ACTION em um conjunto de ativos. Realiza operações estruturais como mover, excluir ou arquivar ativos. Valores suportados para stage_type: add_to_collection, move, delete, archive.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| stage_type | string | obrigatório | O tipo de estágio ACTION a executar enum: add_to_collection · move · delete · archive |
| config | object | opcional | Configuração específica do estágio. add_to_collection: { path: "projects.nike" }. move: { from: "inbox", to: "approved" }. delete: { confirm: true }. archive: { confirm: true }. |
| assets | string[] | obrigatório | Matriz de hashes de ativos para operar |
| dry_run | boolean | opcional | Se verdadeiro, simula a execução sem efeitos colaterais |
OutputStage
tool · estágios de pipeline
Executa um único estágio de pipeline da categoria OUTPUT em um conjunto de ativos. Produz saídas como exportações, notificações ou cópias tee. Valores suportados para stage_type: export, notify, tee.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| stage_type | string | obrigatório | O tipo de estágio OUTPUT a executar enum: export · notify · tee |
| config | object | opcional | Configuração específica do estágio. export: { preset: "client", confirm: true }. notify: { event_type: "pipeline.completed" }. tee: { action: { type: "add_to_collection", path: "backup" } }. |
| assets | string[] | obrigatório | Matriz de hashes de ativos para saída |
| dry_run | boolean | opcional | Se verdadeiro, simula a execução sem efeitos colaterais |
SummarizeStage
tool · estágios de pipeline
Executa um único estágio de pipeline da categoria SUMMARIZE em um conjunto de ativos. Produz dados agregados e estatísticas. Valores suportados para stage_type: count, group_by, stats, histogram.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| stage_type | string | obrigatório | O tipo de estágio SUMMARIZE a executar enum: count · group_by · stats · histogram |
| config | object | opcional | Configuração específica do estágio. count: { group_by: "tool" }. group_by: { field: "mime_type" }. stats: { field: "file_size" }. histogram: { field: "created_at" }. |
| assets | string[] | obrigatório | Matriz de hashes de ativos para resumir |
| dry_run | boolean | opcional | Se verdadeiro, simula a execução sem efeitos colaterais |
Regras de Automação3 ferramentas
Criar, listar e acionar regras de automação
CreateRule
tool · regras de automação
Cria uma regra de automação que aciona um pipeline salvo em eventos, agendamentos ou intervalos de monitoramento. Forneça pipeline_definition_h (hex de 40 caracteres) ou pipeline_name (resolvido automaticamente). Tipos de acionamento: event (dispara em eventos de ativos/pipelines), schedule (baseado em cron), watch (verificação periódica de consulta).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| name | string | obrigatório | Nome da regra (único por tenant) |
| description | string | opcional | Descrição legível do que esta regra faz |
| trigger_config | object | obrigatório | Configuração do acionador com 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 | Configuração opcional de limite de taxa (ex.: { max_executions_per_hour: 10 }) |
| pipeline_vars | object | opcional | Variáveis a injetar no contexto do pipeline quando a regra disparar |
| pipeline_definition_h | string | opcional | Hash hex de 40 caracteres do pipeline salvo a acionar |
| pipeline_name | string | opcional | Nome do pipeline (alternativa a pipeline_definition_h). Resolvido para hash automaticamente. |
ListRules
tool · regras de automação
Lista regras de automação do tenant atual com filtros opcionais. Retorna metadados da regra, incluindo nome, tipo de acionador, status de habilitação e pipeline vinculado.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| enabled | boolean | opcional | Filtrar por status habilitado/desabilitado |
| trigger_type | string | opcional | Filtrar por tipo de acionador enum: event · schedule · watch |
| tenant_id | string ·uuid | opcional | UUID do tenant (opcional - injetado automaticamente pela autenticação via chave de API) |
TriggerRule
tool · regras de automação
Aciona manualmente o processamento de regras de automação. Para schedule/watch: avalia todas as regras devidas do tenant. Para event: despacha para regras baseadas em eventos correspondentes. Retorna resultados de execução para cada regra acionada.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| trigger_type | string | obrigatório | Tipo de acionador a processar: schedule (verificar regras devidas por cron), watch (verificar regras baseadas em consulta), event (despachar evento para regras correspondentes) enum: schedule · watch · event |
| event_type | string | opcional | Tipo de evento a despachar (obrigatório quando trigger_type é "event", ex.: "pipeline.completed") |
| event_data | object | opcional | Dados de carga útil do evento (opcional, passados para regras de evento correspondentes) |
| tenant_id | string ·uuid | obrigatório | UUID do tenant (obrigatório para despacho de eventos) |
Webhooks1 ferramenta
Registrar webhooks para integrações orientadas a eventos
RegisterWebhook
tool · webhooks
Registra uma nova assinatura de webhook para receber notificações de eventos. Retorna o ID do webhook e o segredo de assinatura (exibido uma única vez). Suporta eventos: pipeline.completed, pipeline.failed, pipeline.export.completed, test.ping.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| name | string | obrigatório | Nome legível para a assinatura do webhook |
| url | string | obrigatório | URL do endpoint HTTPS para receber eventos do webhook (deve ser público, sem IPs privados) |
| events | string[] | obrigatório | Tipos de eventos para assinar (ex.: ["pipeline.completed", "pipeline.failed"]) |
| description | string | opcional | Descrição opcional da finalidade do webhook |
| enabled | boolean | opcional | Se o webhook está habilitado (padrão: true) |
| timeout_ms | number | opcional | Tempo limite de solicitação em milissegundos, 1000-60000 (padrão: 10000) |
Não categorizadas29 ferramentas
Não categorizadas
GetAssetDetails
tool · não categorizadas
Recupera detalhes abrangentes de um ativo específico pelo seu hash SHA-1, incluindo como foi criado. Responde diretamente 'qual prompt, modelo e fluxo de trabalho produziram isto?' — sem necessidade de download: prompts.positive\/prompts.negative\ contêm o prompt, models\[\]\ lista todos os modelos que o fluxo de trabalho carregou (nome, tipo como checkpoint/unet/lora/vae, node_id do carregador), workflow.workflow\_json\ é o grafo completo do ComfyUI (com workflow.tool\_name\, node\_count\, custom\_nodes\), e generation\_parameters\ contém as configurações do amostrador (model_name, seed, steps, cfg_scale, sampler, scheduler) quando foram lidas de um nó KSampler padrão, caso contrário null (o grafo ainda as contém). provenance.lineage\_source\ indica de onde veio essa linhagem: 'extracted' (lido pelo Numonic do arquivo armazenado; prompts.source\/workflow.source\ são então 'extracted'), 'client_asserted' (apenas a afirmação do uploader), ou 'unknown' (nada afirmado ou encontrado). Também retorna título, descrição, tags, coleções, proveniência (prompt de criação, ativos pais), informações de incorporação e direitos autorais. Para registros da Biblioteca de Modelos desses modelos (modelo base, palavras de acionamento, uso), chame GetAssetModels. Opcionalmente, gera uma URL de download assinada para o arquivo original (válida por 5 minutos).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| asset_h | string | obrigatório | O Hash do Ativo (SHA-1) do ativo a recuperar |
| include_download_url | boolean | opcional | Se verdadeiro, inclui uma URL assinada de curta duração para baixar o binário original do ativo. Padrão: false. |
| include_raw_metadata | boolean | opcional | Se verdadeiro, também retorna a saída bruta do extrator (extracted_metadata) e o workflow_graph nó por nó. Isso pode ter dezenas de kilobytes; a resposta padrão já contém prompts, modelos e workflow.workflow_json. Padrão: false. |
BulkUpdateAssetTags
tool · não categorizadas
Adiciona ou remove um conjunto de tags em até 100 ativos em uma única chamada. Comportamento por ativo: 'add' mescla no conjunto de tags existente (sem duplicatas); 'remove' exclui as tags listadas de cada ativo. Ativos cujo conjunto de tags não muda são ignorados silenciosamente e relatados como inalterados na resposta. Escopo por tenant; usa o mesmo caminho RLS que PATCH /api/v1/assets/bulk-tag.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| asset_hs | string[] | obrigatório | Matriz de hashes de ativos (SHA-1, hex de 40 caracteres) para aplicar a operação. Mínimo 1, máximo 100. |
| operation | string | obrigatório | 'add' mescla as tags no conjunto de tags existente de cada ativo (sem duplicatas); 'remove' as exclui. Para semântica de substituição total em um único ativo, use UpdateAsset. enum: add · remove |
| tags | string[] | obrigatório | Strings de tags para adicionar ou remover. Mínimo 1 caractere, máximo 100 caracteres por tag. Mínimo 1 tag, máximo 50 tags por chamada. |
UpdateAsset
tool · não categorizadas
Atualização parcial dos metadados escalares de um único ativo: descrição, título e/ou tags. A atualização de tags nesta ferramenta SUBSTITUI todo o conjunto de tags existente; para operações incrementais de adicionar/remover em vários ativos, use BulkUpdateAssetTags. Pelo menos um de descrição, título ou tags deve ser fornecido. Escopo por tenant; usa o mesmo caminho RLS que PATCH /api/v1/assets/[assetH].
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| asset_h | string | obrigatório | Hash do ativo (SHA-1, hex de 40 caracteres) do ativo a atualizar. |
| description | string | opcional | Nova descrição opcional do ativo (máx. 5000 caracteres). Substitui qualquer descrição existente literalmente. |
| title | string | opcional | Novo título opcional do ativo (máx. 500 caracteres). |
| tags | string[] | opcional | Novo conjunto de tags opcional. SUBSTITUI todo o conjunto de tags existente. Para adição/remoção incremental, use BulkUpdateAssetTags. Mín. 0 tags, máx. 500. Cada tag de 1 a 100 caracteres. |
ExportCollectionAsPdf
ferramenta · não categorizada
Exporta uma coleção como documento PDF. Retorna o PDF como string codificada em base64, juntamente com contagem de páginas e metadados de tempo de processamento. A API web lida com layout, paginação e remoção opcional de marca d'água.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| collection_h | string | obrigatório | Hash da coleção (SHA-1, 40 caracteres hex) a exportar |
| remove_watermark | boolean | opcional | Se deve remover a marca d'água da Numonic do PDF exportado. Padrão: false. |
AddTextCardToCollection
ferramenta · não categorizada
Adiciona um cartão de texto rico (slide) a uma coleção. Cartões de texto são renderizados como slides completos em exportações PDF e podem conter título, corpo de texto, marcadores e um destaque de chamada. Suporta fundos escuros, gradientes e claros com cor de destaque hex opcional.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| collection_h | string | obrigatório | Hash da coleção (SHA-1, 40 caracteres hex) |
| heading | string | opcional | Texto do título do cartão |
| heading_size | string | opcional | Tamanho do título: xl, lg ou md enum: xl · lg · md |
| body | string | opcional | Texto do corpo do cartão |
| bullets | string[] | opcional | Matriz de strings de marcadores |
| accent_text | string | opcional | Texto de chamada destacado |
| background | string | opcional | Estilo de fundo. Padrão: dark enum: dark · gradient · light |
| accent_color | string | opcional | Código de cor hex para elementos de destaque (ex.: #3B82F6) |
| layout | string | opcional | Estilo de layout. Padrão: centered enum: centered · left-aligned |
| position | integer | opcional | Posição na ordenação da coleção (base 0) |
SearchModels
ferramenta · não categorizada
Pesquisa na Biblioteca de Modelos por modelos (LoRAs, checkpoints, UNETs, etc.) por nome, tipo ou arquitetura base. Retorna entidades de modelo com metadados, não ativos. Use GetAssetModels para encontrar ativos por modelo.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | opcional | UUID do tenant |
| query | string | opcional | Pesquisa de texto em nome do modelo, nome de exibição e descrição. Suporta correspondência 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 arquitetura base: sdxl, flux, sd15, sd3, sd35, pony, illustrious, noobai, hunyuan, etc. |
| limit | integer | opcional | Máximo de resultados a retornar (padrão: 50) |
| offset | integer | opcional | Deslocamento para paginação (padrão: 0) |
GetModelDetails
ferramenta · não categorizada
Obtém detalhes completos de um modelo específico, incluindo metadados, histórico de versões, contagem de uso de ativos e contagem de visualizações.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | opcional | UUID do tenant |
| model_hash | string | obrigatório | Chave hash SHA-1 do modelo (de models_h.model) |
GetAssetModels
ferramenta · não categorizada
Obtém os registros da Biblioteca de Modelos para cada modelo usado para gerar um ativo específico (checkpoints, UNETs, LoRAs com pesos, VAEs, CLIP, upscalers), com modelo base, tipo e fonte de detecção. Escopo limitado ao seu tenant: um ativo que seu tenant não possui retorna nenhum modelo. Para o prompt e o grafo de workflow do ComfyUI, chame GetAssetDetails.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | opcional | UUID do tenant |
| asset_hash | string | obrigatório | Chave hash SHA-1 do ativo |
LinkModelToAsset
ferramenta · não categorizada
Vincula manualmente um modelo a um ativo (para fontes não-ComfyUI onde a detecção automática não está disponível).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | opcional | UUID do tenant |
| model_hash | string | obrigatório | Chave hash SHA-1 do modelo |
| asset_hash | string | obrigatório | Chave hash SHA-1 do ativo |
| model_weight | number | opcional | Valor strength_model do LoRA (ex.: 0,75). Nulo para checkpoints. |
| detection_source | string | opcional | Como este vínculo foi descoberto (padrão: manual_tag) |
GetModelVersions
ferramenta · não categorizada
Obtém o histórico de versões de um modelo, incluindo etapas de treinamento, pontuações de qualidade e sinalizador de recomendação.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| model_hash | string | obrigatório | Chave hash SHA-1 do modelo |
| include_deleted | boolean | opcional | Incluir versões excluídas de forma suave (padrão: false) |
AddModelVersion
ferramenta · não categorizada
Adiciona uma versão a um modelo com metadados de treinamento, pontuação de qualidade e sinalizador de recomendação.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| model_hash | string | obrigatório | Chave hash SHA-1 do modelo |
| version_tag | string | obrigatório | Rótulo da versão (ex.: v1.0, v2.0, epoch10) |
| version_notes | string | opcional | Registro de alterações ou descrição desta versão |
| training_steps | integer | opcional | Total de etapas de treinamento |
| training_epochs | integer | opcional | Total de épocas de treinamento |
| training_config | object | opcional | Hiperparâmetros de treinamento: {"lr": 0.0001, "optimizer": "AdamW"} |
| quality_score | number | opcional | Classificação de qualidade (0-10) |
| is_recommended | boolean | opcional | Marcar como a versão recomendada para este modelo |
| trained_at | string ·date-time | opcional | Quando esta versão foi treinada |
CreateExperiment
ferramenta · não categorizada
Cria uma coleção de experimento para fluxos de trabalho estruturados de comparação de imagens (benchmarking de modelos, teste A/B de prompts, avaliação de estilo). Retorna o hash da coleção de experimento.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string | obrigatório | UUID do tenant |
| display_name | string | obrigatório | Nome legível do experimento |
| description | string | opcional | Descrição do experimento |
| hypothesis | string | opcional | O que este experimento testa |
| independent_variable | string | opcional | O que varia entre execuções (ex.: "condição do prompt", "modelo", "LoRA") |
| control_variable | string | opcional | O que é mantido constante (ex.: "conjunto de sementes", "resolução") |
| model_name | string | opcional | Modelo de geração primário (ex.: "FLUX.2 Dev") |
| workflow_name | string | opcional | Workflow de geração (ex.: "txt2img") |
| resolution | string | opcional | Resolução da imagem (ex.: "1024x1024") |
| domain_context | object | opcional | Metadados específicos do domínio como JSON (ex.: {"grammar_version": "v3"}) |
RegisterRun
ferramenta · não categorizada
Adiciona um ativo a um experimento como execução com contexto completo (condição, semente, prompt, modelo, parâmetros de domínio).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| collection_h | string | obrigatório | Hash da coleção de experimento (hex de 40 caracteres) |
| asset_h | string | obrigatório | Hash do ativo a registrar como execução (hex de 40 caracteres) |
| condition_id | string | opcional | Valor da variável independente para esta execução (ex.: "cond2b", "model_A") |
| variant_label | string | opcional | Rótulo de variante legível (ex.: "Prompt compilado") |
| seed | integer | opcional | Semente de geração |
| prompt_text | string | opcional | Prompt exato usado para geração |
| model_name | string | opcional | Modelo para esta execução específica (substitui o nível do experimento) |
| run_params | object | opcional | Parâmetros de execução específicos do domínio como JSON |
| outcome_tags | string[] | opcional | Tags de classificação de resultado (ex.: ["text_literalization", "best_in_set"]) |
| position | integer | opcional | Posição/ordem dentro do experimento |
ScoreRun
ferramenta · não categorizada
Pontua uma execução de experimento em dimensões definidas pelo usuário. Cria uma anotação de avaliação. As dimensões são definidas pelo experimento (ex.: qualidade, aderência, coerência).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| collection_item_h | string | obrigatório | Hash do item da coleção para a execução a pontuar (hex de 40 caracteres) |
| scores | object | obrigatório | Dimensões de pontuação como pares chave-valor (ex.: {"quality": 4, "coherence": 5}). Valores são de 1 a 5. |
| flags | object | opcional | Sinalizadores booleanos (ex.: {"prompt_leakage": true, "text_literalization": false}) |
| evaluator_type | string | opcional | Quem/o que realizou a avaliação (padrão: "human") enum: human · vlm_assisted · embedding_similarity |
| comments | string | opcional | Comentários de avaliação em formato livre |
CompareRuns
ferramenta · não categorizada
Cria uma comparação A/B pareada entre duas execuções de experimento, registrando qual item vence em cada dimensão de pontuação.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| collection_h | string | obrigatório | Hash da coleção de experimento (hex de 40 caracteres) |
| item_a | string | obrigatório | Hash do item da coleção da primeira execução (hex de 40 caracteres) |
| item_b | string | obrigatório | Hash do item da coleção da segunda execução (hex de 40 caracteres) |
| winners | object | obrigatório | Mapeamento dimensão-para-vencedor (ex.: {"quality": "<item_a_hash>", "coherence": "<item_b_hash>"}) |
| evaluator_type | string | opcional | Quem/o que realizou a comparação (padrão: "human") enum: human · vlm_assisted · embedding_similarity |
| notes | string | opcional | Notas da comparação |
GetExperimentSummary
ferramenta · não categorizada
Obtém resultados agregados do experimento: contagem de execuções, detalhamento por condição, distribuição de tags de resultado e contagem de comparações.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| collection_h | string | obrigatório | Hash da coleção de experimento (hex de 40 caracteres) |
CreatePrompt
ferramenta · não categorizada
Cria um novo prompt na Biblioteca de Prompts. Retorna o hash do prompt e informações de versão.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| prompt_text | string | obrigatório | Conteúdo do texto do prompt (obrigatório) |
| name | string | opcional | Nome legível do prompt |
| description | string | opcional | Descrição do prompt |
| target_model | string | opcional | Modelo alvo (ex.: midjourney, dall-e, flux) |
| category | string | opcional | Categoria do prompt (ex.: paisagem, retrato) |
| tags | string[] | opcional | Tags do prompt para organização |
GetPrompt
ferramenta · não categorizada
Obtém um prompt pelo hash ID com histórico completo de versões e avaliações.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| prompt_h | string | obrigatório | Hash do hub de prompts (hex de 40 caracteres) |
SearchPrompts
ferramenta · não categorizada
Pesquisa prompts com filtros opcionais de categoria, target_model e paginação.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| category | string | opcional | Filtrar por categoria |
| target_model | string | opcional | Filtrar por modelo alvo |
| limit | integer | opcional | Tamanho da página (padrão 20, máx. 100) |
| offset | integer | opcional | Deslocamento de paginação (padrão 0) |
RenderPrompt
ferramenta · não categorizada
Renderiza um modelo de prompt substituindo os espaços reservados {{variable}} pelos valores fornecidos.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| prompt_h | string | obrigatório | Hash do prompt hub (hex de 40 caracteres) |
| variables | object | opcional | Variáveis de template como pares chave-valor (ex.: {"subject": "cityscape"}) |
RegisterProspect
ferramenta · não categorizada
Registra ou atualiza um prospect de cold outreach: grava o hub prospects_h + link de escopo do tenant + prospect_profile_s e, opcionalmente, prospect_research_s (gravado quando qualquer campo de pesquisa estiver presente, não apenas pain_hypothesis — #2000) e prospect_deal_s (quando trial_start_date ou agreed_price estiver presente — #2000). Pelo menos um dos campos email / linkedin_url / profile_url / handle / website é obrigatório (#1997); a precedência de chave quando mais de um está presente é email > linkedin_url > profile_url > handle > website. Somente acréscimo — chamar novamente adiciona novas linhas satélite.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| prospect | object | obrigatório | Dados do prospect. Pelo menos um dos campos email / linkedin_url / profile_url / handle / website é obrigatório (validado no servidor). |
| record_source | string | obrigatório | Tag de origem, ex.: "cold-outreach-studios:studios-2026-q2". |
SetProspectOwner
ferramenta · não categorizada
Atribui ou reatribui o proprietário de um prospect (#1999). Somente acréscimo — grava uma nova linha prospect_owner_s; nunca altera prospect_outreach_touch_s, portanto a reatribuição não reescreve o histórico de contatos. Definido independentemente de prospect_outreach_touch_s.sent_by.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| prospect_h | string | obrigatório | Hash do hub do prospect (SHA-1). |
| owner | string | obrigatório | |
| record_source | string | obrigatório |
LogOutreachTouch
ferramenta · não categorizada
Adiciona um contato ao log de saída e avança o estado da sequência de outreach do prospect. channel aceita email, linkedin, discord, github, contact_form ou other (#1998). Ambas as gravações são somente acréscimo.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| prospect_h | string | obrigatório | Hash do hub do prospect (SHA-1). |
| touch | object | obrigatório | |
| record_source | string | obrigatório |
GetProspectState
ferramenta · não categorizada
Retorna o estado completo do prospect: perfil mais recente + pesquisa + estado + supressão, além de todos os contatos e respostas, e contact_link se a transferência já ocorreu.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| prospect_h | string | obrigatório | Hash do hub do prospect (SHA-1). |
SearchProspects
ferramenta · não categorizada
Filtra prospects por campanha, status atual da sequência, pontuação mínima de ICP, vertical, substring da conta ou proprietário (#1999, correspondência exata). Prospects suprimidos (suppressed_until no futuro) são excluídos por padrão. Limite padrão 50, máximo 200. Cada linha de resultado inclui o proprietário atual (null se não atribuído).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| filters | object | opcional |
SuppressProspect
ferramenta · não categorizada
Suprime um prospect com um motivo e data final opcional. Marca todas as sequências ativas do prospect como suprimidas. unsubscribe é SEMPRE permanente (qualquer suppressed_until é ignorado). Para not_interested / wrong_person, omita suppressed_until para supressão permanente ou informe uma data futura para uma supressão finita. not_now exige suppressed_until (a data de reengajamento).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| prospect_h | string | obrigatório | |
| reason | string | obrigatório | enum: unsubscribe · wrong_person · not_now · not_interested |
| suppressed_until | string,null ·date | opcional | Data ISO futura AAAA-MM-DD quando a supressão é suspensa. Omita (ou null) para supressão permanente; obrigatório para not_now; ignorado para unsubscribe (sempre permanente). |
| record_source | string | obrigatório |
LogReply
ferramenta · não categorizada
Registra uma resposta recebida com a classificação de triagem de respostas do cold-outreach-studios. Avança o estado da sequência: positivo → responded, not_now/wrong_person/unsubscribe/not_interested/bounced → suppressed, ooo deixa o estado inalterado. bounced (#1998) é uma falha de entrega, distinta de qualquer classificação de recusa. reply.refusal_class (#2000) opcionalmente codifica uma recusa T (timing) ou P (problem), válida apenas junto a uma classificação em formato de recusa. Em resposta positiva, gera prospect_to_contact_l para que lead-response v0.2 capture o contato agora aquecido.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| prospect_h | string | obrigatório | |
| reply | object | obrigatório | |
| record_source | string | obrigatório |
SearchContacts
ferramenta · não categorizada
Lista contatos do CRM em um pipeline (community | enterprise | investor) com estágio opcional e busca de texto livre. Encapsula get_pipeline_contacts; retorna o perfil mais recente, estágio do pipeline, atividade (last_contacted, next_follow_up), além de campos satélite específicos do pipeline (investor: firm_name, investor_type, investment_amount, round, seis_eis_status). Limite padrão 50, máximo 200. tenant_id é injetado automaticamente pela autenticação via chave de API.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| pipeline | string | obrigatório | Qual pipeline do CRM listar. 'investor' para contatos de captação. enum: community · enterprise · investor |
| stage | string | opcional | Filtro opcional de estágio do pipeline (ex.: "lead", "engaged", "diligence"). |
| search | string | opcional | Correspondência opcional de substring sem diferenciar maiúsculas/minúsculas contra nome do contato e linkedin_url. |
| limit | integer | opcional | |
| offset | integer | opcional |
GetRelationshipSummary
ferramenta · não categorizada
Uma resposta para "quem é este, quem é o dono, o que vem a seguir e quando vence" para um contato do CRM, prospect ou organização (#2637). Resolve contatos duplicados mesclados para o registro canônico, une prospects transferidos e a organização, reconcilia o proprietário (proprietário do prospect > assigned_to do contato > responsável pela tarefa aberta, todos os candidatos retornados com owner_conflict), seleciona a próxima ação com vencimento mais próximo entre tarefas abertas, follow-ups, contatos de outreach ativos e datas de reengajamento, e retorna uma lista de atividades em ordem cronológica reversa (contatos, respostas, notas, mudanças de estágio, tarefas, atualizações de negócio). Mesmos dados do painel GUI do CRM administrativo.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tenant_id | string ·uuid | obrigatório | UUID do tenant |
| entity_type | string | obrigatório | A qual hub entity_id pertence. enum: contact · prospect · organization |
| entity_id | string | obrigatório | Hash do hub (SHA-1) do contato, prospect ou organização — ex.: um contato de SearchContacts ou um prospect_h de SearchProspects. |
| activity_limit | integer | opcional | Número máximo de entradas de atividade retornadas (padrão 50). |
Recursos(5)
Recursos são dados somente leitura navegáveis que clientes MCP podem ler para contexto — estrutura de coleções, cotas de armazenamento, predefinições disponíveis. Diferente das ferramentas, recursos não modificam estado.
resources/list resources/read:
{"jsonrpc":"2.0","method":"resources/read","params":{"uri":"numonic://collections"},"id":3}
numonic://storage
Uso de Armazenamento
recurso
Armazenamento do tenant: GB usados, cota, porcentagem, sinalizador de limite excedido. Verifique antes de enviar grandes lotes.
numonic://export-presets
Predefinições de Exportação
recurso
Predefinições de privacidade disponíveis com metadados de conformidade (EU AI Act, CA SB 942).
numonic://pipeline-templates
Modelos de Pipeline
recurso
Modelos de pipeline do sistema e do tenant. Navegue antes de criar pipelines personalizados.
numonic://asset/{asset_h}
Detalhes do Ativo
recurso · modelo
Metadados completos de um ativo específico. Informe o hash hexadecimal de 40 caracteres do ativo. (Modelo de URI)
Prompts(5)
Fluxos de trabalho guiados em várias etapas que ensinam agentes a maneira canônica de concluir tarefas comuns. Eles retornam instruções pré-escritas que encadeiam várias chamadas de ferramentas.
prompts/get:
{"jsonrpc":"2.0","method":"prompts/get","params":{"name":"search-and-curate","arguments":{"query":"tool:midjourney AND tag:approved"}},"id":5}
Ingerir e Organizar
prompt ingest-and-organize
Envie um novo ativo e arquive-o na coleção correta.
Fluxo de trabalho: StoreAsset → ListCollections → AddToCollection
| Argumento | Obrigatório | Descrição |
|---|---|---|
| filename | obrigatório | Nome do arquivo sendo enviado |
| mime_type | obrigatório | Tipo MIME (ex.: image/png) |
| collection_path | opcional | Caminho da coleção de destino |
Exportar para Cliente
prompt export-for-client
Exporta ativos com remoção de metadados consciente de privacidade para entrega ao cliente.
Fluxo de trabalho: SearchAssets ou GetCollectionAssets → ExportAssets
| Argumento | Obrigatório | Descrição |
|---|---|---|
| query_or_collection | obrigatório | Consulta de busca ou hash da coleção |
| preset | opcional | Predefinição de privacidade (padrão: client) |
Auditar Saúde do Tenant
prompt audit-tenant-health
Avalia uso de armazenamento, qualidade do índice de busca e saúde geral do tenant.
Fluxo de trabalho: GetTenantStorageDetails → GetSearchAnalytics → resumir
Explorar Linhagem
prompt explore-lineage
Rastreia a cadeia completa de evolução de um ativo Midjourney por variações, upscales e remixes.
Fluxo de trabalho: GetMidjourneyEvolutionChain → GetCreativeSession → sintetizar
| Argumento | Obrigatório | Descrição |
|---|---|---|
| asset_h | obrigatório | Hash do ativo (hex de 40 caracteres) |
| depth | opcional | Profundidade máxima da cadeia (padrão: 10) |
Códigos de Erro
O servidor MCP usa códigos de erro padrão JSON-RPC 2.0.
| Código | Nome | Significado |
|---|---|---|
| -32700 | Parse Error | JSON malformado no corpo da requisição |
| -32600 | Invalid Request | Campo jsonrpc ou method ausente |
| -32601 | Method Not Found | Nome de método desconhecido |
| -32602 | Invalid Params | Parâmetros ausentes ou inválidos |
| -32603 | Internal Error | Exceção no lado do servidor |
Códigos de Status HTTP
Erros de parse e requisições inválidas retornam HTTP 400. Todos os outros erros (incluindo falhas de ferramentas) retornam HTTP 200 com o erro no corpo da resposta JSON-RPC — conforme a especificação JSON-RPC.
Erros no Nível de Ferramenta
Erros de ferramentas são retornados no array content do resultado com isError: true:
{"content":[{"type":"text","text":"Error: …"}],"isError":true}
Detalhes do Protocolo
| Protocolo | Model Context Protocol (JSON-RPC 2.0) |
|---|---|
| Transporte | Streamable HTTP (POST) |
| Versões suportadas | 2025-03-26 (principal), 2024-11-05 (compatível com versões anteriores) |
| Nome do servidor | Numonic-MCP-Server |
| Versão do servidor | 1.0.0 |
| Ferramentas | 66 |
| Recursos | 5 (4 estáticos + 1 modelo de URI) |
| Prompts | 5 fluxos de trabalho guiados |
Referência do Servidor MCP: Ferramentas, Recursos e Configuração do Cliente