# Referência das ferramentas MCP

> Todas as ferramentas do servidor MCP do Nodaro, por finalidade: a permissão de cada uma, como os jobs informam o resultado e como ler cada ferramenta.

Source: https://nodaro.ai/pt-BR/docs/mcp/tools

As **ferramentas MCP do Nodaro** são as ações que um assistente de IA pode realizar na sua conta do Nodaro depois de se conectar ao [servidor MCP do Nodaro](https://nodaro.ai/docs/mcp). São cerca de 200, agrupadas aqui por finalidade: gerar mídia, editá-la, gerenciar entidades, criar e executar workflows e dirigir produções completas. Cada página lista os nomes exatos das ferramentas, a permissão de que cada uma precisa, os principais parâmetros, o que ela retorna e quanto custa.

## Os grupos de ferramentas
| Grupo | Para que servem |
| --- | --- |
| [Jobs](https://nodaro.ai/docs/mcp/tools/jobs) | Verificar, aguardar e diagnosticar jobs e execuções |
| [Uploads](https://nodaro.ai/docs/mcp/tools/uploads) | Trazer suas próprias imagens, áudios e vídeos para o Nodaro |
| [Galeria e mídias](https://nodaro.ai/docs/mcp/tools/gallery-and-assets) | Navegar pela galeria e pelos uploads, mostrar um resultado no chat e marcar favoritos |
| [Modelos, créditos e predefinições](https://nodaro.ai/docs/mcp/tools/models-and-credits) | Listar os modelos com seus recursos e preços, ler o seu saldo e aplicar predefinições de nó |
| [Espaços de trabalho](https://nodaro.ai/docs/mcp/tools/workspaces) | Escolher o espaço de trabalho da organização em que uma sessão trabalha |
| [Projetos e workflows](https://nodaro.ai/docs/mcp/tools/projects-and-workflows) | Criar, editar, importar, exportar e executar workflows, e aprender como os nós são montados |
| [Apps e componentes](https://nodaro.ai/docs/mcp/tools/apps-and-components) | Executar apps publicados e componentes salvos |
| [Pipelines](https://nodaro.ai/docs/mcp/tools/pipelines) | Iniciar, orientar e aprovar pipelines do **História → vídeo** (Story to Video) |
| [Prompts e texto](https://nodaro.ai/docs/mcp/tools/prompts-and-text) | Escrever prompts melhores, escrever roteiros e escolher o melhor entre vários resultados |
| [Imagem](https://nodaro.ai/docs/mcp/tools/image) | Gerar, transformar, editar, compor e descrever imagens |
| [Vídeo](https://nodaro.ai/docs/mcp/tools/video) | Gerar, estender, mudar o estilo e aumentar a resolução de vídeos, e fazer pessoas falarem e se moverem |
| [Edição de vídeo](https://nodaro.ai/docs/mcp/tools/video-editing) | Cortar, juntar, repetir em loop, legendar, sobrepor e montar vídeos |
| [Análise e listas de edição](https://nodaro.ai/docs/mcp/tools/analysis-and-edl) | Analisar um vídeo cena a cena, detectar silêncio, sincronizar gravações e renderizar listas de decisões de edição |
| [Áudio](https://nodaro.ai/docs/mcp/tools/audio) | Fala, diálogos, vozes, dublagem, efeitos sonoros, transcrição e limpeza |
| [Música](https://nodaro.ai/docs/mcp/tools/music) | Músicas e instrumentais com o Suno e outros modelos de música |
| [Personagens](https://nodaro.ai/docs/mcp/tools/characters) | Criar personagens, gerar seus retratos e variações e animá-los |
| [Locais](https://nodaro.ai/docs/mcp/tools/locations) | Criar locais e gerar planos de estabelecimento e clipes de atmosfera |
| [Objetos e criaturas](https://nodaro.ai/docs/mcp/tools/objects-and-creatures) | Adereços, produtos, animais e criaturas com aparência fixa |
| [Sequência de tomadas e Diretor de vídeo](https://nodaro.ai/docs/mcp/tools/shot-sequence-and-video-director) | Vídeos narrados de gráficos animados, sincronizados com a narração |
| [Produções do Studio](https://nodaro.ai/docs/mcp/tools/studio-productions) | Filmes que você pode continuar editando no editor do Studio |
| [Recast](https://nodaro.ai/docs/mcp/tools/recast) | Um filme escrito como um único roteiro JSON e renderizado como um projeto do Recast |
| [Cenas 3D](https://nodaro.ai/docs/mcp/tools/3d-scenes) | Cenas 3D editáveis, renderizadas em vídeo |
| [Utilitários, receitas e skills](https://nodaro.ai/docs/mcp/tools/utility) | Testar a conexão, carregar receitas e skills e montar vídeos UGC |

## Permissões
Cada ferramenta precisa de uma ou mais permissões OAuth (escopos), que você concede na tela de consentimento ao se conectar. Uma ferramenta cujas permissões não foram concedidas fica totalmente fora da lista de ferramentas. O assistente nunca a vê, então não pode chamá-la e falhar.

| Escopo | Ferramentas |
| --- | --- |
| `workflows:read` | `list_projects`, `get_project`, `list_workflows`, `get_workflow`, `get_workflow_json`, `export_workflow`, `list_components`, `get_component_inputs`, `get_recast_status`, `validate_studio_plan`, `list_studio_productions`, `get_studio_production`, `plan_studio_export` |
| `workflows:write` | `create_workflow`, `delete_workflow`, `update_workflow_json`, `import_workflow`, `import_recast_script`, `create_studio_production`, `import_studio_production`, `edit_studio_production`, `share_studio_production`, `clone_studio_production` |
| `workflows:execute` | `run_workflow`, `run_app`, `run_component`, `delete_app_run`, todas as ferramentas de geração, edição e análise de imagem, vídeo, áudio, música, entidades e cenas 3D, as ferramentas de prompt, `reduce`, as ferramentas de sequência de tomadas, `create_explainer`, `create_launch_video`, `start_recast`, `resolve_recast_gate` |
| `workflows:write` e `workflows:execute` juntas | `describe_studio_production`, `generate_studio_still`, `generate_studio_keyframe`, `generate_studio_clip`, `new_studio_shot_from_frame`, `voice_studio_shot`, `revoice_studio_clip`, `score_studio_production` |
| `jobs:read` | `list_jobs`, `get_job`, `wait_for_job`, `diagnose_run` |
| `assets:read` | `browse_gallery`, `browse_uploads`, `list_favorites`, `get_asset`, `display_asset`, `get_app_run`, `list_characters`, `get_character`, `list_locations`, `get_location`, `list_objects`, `get_object`, `list_creatures`, `get_creature` |
| `assets:write` | `favorite_asset`, `create_character`, `update_character`, `approve_portrait`, `recaption_character`, `create_location`, `update_location`, `approve_main_image`, `recaption_location`, `approve_object_main_image`, `recaption_object`, `approve_creature_main_image`, `recaption_creature` e as nove ferramentas de upload |
| `credits:read` | `check_balance`, `credit_transactions` |
| `apps:read` | `list_apps`, `get_app_inputs` |
| `presets:read` | `list_node_presets`, `get_node_preset` |
| `pipelines:read` | `get_pipeline_stage_chat`, `get_pipeline_status`, `pipeline_pending_approvals` |
| `pipelines:execute` | `branch_pipeline`, `start_pipeline` |
| `pipelines:approve` | `chat_pipeline_stage`, `apply_chat_proposal` |
| `workspaces:read` | `list_workspaces` |
| `workspaces:write` | `select_workspace` |

Estas ferramentas não precisam de permissão e ficam sempre visíveis, nas edições que as têm: `ping`, `list_models`, `start_film_director`, `start_video_director`, `start_workflow_editor`, `get_node_skill`, `get_picker_catalog`, `list_shot_shapes`, `get_shot_shape`, `list_brand_presets`, `get_recipe`, `get_studio_production_skill`, `get_recast_authoring_skill`, `validate_recast_script`, `build_ugc_creator`, `build_ugc_clips` e `build_ugc_cards`.

As ferramentas que precisam de duas permissões só aparecem quando as duas foram concedidas. Uma conexão com apenas uma das duas não vê nenhuma dessas ferramentas.

## Como um job informa o resultado
A maioria das ferramentas de geração inicia um **job** e responde na hora com uma linha como `image collage started (id 7f3c…).` O job é executado no Nodaro, e o resultado também é sempre salvo na sua biblioteca.

- **Nos clientes que exibem MCP Apps**, como o Claude na web, a ferramenta mostra um cartão. O cartão mostra o progresso em tempo real e depois o resultado pronto. As ferramentas de imagem, vídeo e áudio têm cartões próprios. Todas as outras ferramentas de job compartilham um cartão que detecta o tipo de saída. Ele mostra um player de vídeo, imagem ou áudio, um texto com o botão **Copy** para roteiros, letras, transcrições e dados de alinhamento, ou as saídas empilhadas de um componente.
- **Nos outros clientes**, o assistente verifica o job com [`get_job`](https://nodaro.ai/docs/mcp/tools/jobs#get_job) a cada 5 a 10 segundos, ou fica em espera por até 120 segundos com [`wait_for_job`](https://nodaro.ai/docs/mcp/tools/jobs#wait_for_job). Uma imagem costuma ficar pronta em até um minuto. Um vídeo costuma levar de 2 a 10 minutos.
- **As execuções de workflows e apps** retornam um ID de execução em vez de um ID de job. Verifique-o com [`get_app_run`](https://nodaro.ai/docs/mcp/tools/gallery-and-assets#get_app_run).

Os clientes compatíveis com a API `tasks` do MCP também recebem o progresso por ela. Quando um job aguarda revisão humana, numa implantação que revisa os resultados, a task do MCP mostra o status `input_required`. Essa decisão cabe ao revisor: não execute o job de novo.

## O projeto mcp
As ferramentas de workflow trabalham dentro de um único projeto chamado **mcp**. O Nodaro cria esse projeto na primeira vez que um assistente precisa dele, e o painel lista os workflows dele em **Workflows MCP**. Nessa aba, você pode abri-los, movê-los ou excluí-los como qualquer outro workflow.

| Ferramentas | O que podem acessar |
| --- | --- |
| `list_projects`, `get_project` | Todos os seus projetos, somente leitura |
| `list_workflows`, `get_workflow`, `get_workflow_json` | Workflows do projeto mcp |
| `create_workflow`, `delete_workflow`, `update_workflow_json`, `import_workflow` | Workflows do projeto mcp |
| `export_workflow` | Qualquer um dos seus workflows |
| `run_workflow` | Workflows do projeto mcp |

Para que um assistente trabalhe num workflow de outro projeto, exporte-o com `export_workflow` e importe o pacote com `import_workflow`. A cópia vai para o projeto mcp, e o original continua intacto.

## Como ler a seção de uma ferramenta
Todas as ferramentas destas páginas seguem o mesmo formato:

- **O título** é o nome exato da ferramenta, por exemplo `generate_image`. Os assistentes chamam as ferramentas por esses nomes.
- **As primeiras linhas** dizem o que a ferramenta faz, a permissão de que ela precisa, quanto custa e se ela existe somente no Nodaro Cloud.
- **A tabela de parâmetros** lista os principais parâmetros com o tipo de cada um. Os parâmetros obrigatórios estão marcados como **Obrigatório**. Os valores padrão e os limites ficam nas observações.
- **Retorna** diz o que volta: na maioria das vezes, um ID de job; às vezes, um resultado, como um plano ou uma lista.

A descrição da própria ferramenta, que o assistente lê ao se conectar, é a palavra final sobre parâmetros e limites. O preço na descrição de uma ferramenta pode ser diferente do valor cobrado numa execução. [`list_models`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_models) retorna os preços atuais dos modelos. O botão **Executar** de um nó mostra o preço da execução.

## Convenções comuns a muitas ferramentas
- **Mídia por URL ou por ID.** As ferramentas que recebem mídia aceitam uma URL `https` pública, como `image_url`, ou um ID do Nodaro, como `image_asset_id`. O ID pode ser o do job que gerou a mídia ou o de um upload.
- **Modelos por ID.** Um parâmetro `model` recebe um ID de modelo de [`list_models`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_models), que também retorna as proporções, resoluções, durações e preços de cada modelo.
- **Predefinições.** `generate_image`, `generate_video`, `generate_music`, `generate_speech` e `text_to_audio` aceitam um `presetId` de [`list_node_presets`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_node_presets). Os campos que você mesmo informa substituem os da predefinição.
- **Tokens de nova tentativa.** `run_workflow`, `run_app`, `run_component` e várias ferramentas de produção aceitam `client_request_id`: de 8 a 128 caracteres entre letras, dígitos e `_ - . :`. Reutilize o mesmo valor ao repetir uma chamada que expirou, e o Nodaro não inicia nem cobra o trabalho duas vezes.
- **Cotações antes de gastar.** Algumas ferramentas calculam o preço de um trabalho sem iniciá-lo, por exemplo as ferramentas do Studio com `dry_run: true` e `start_recast` sem `confirm`.

## Ferramentas somente no Nodaro Cloud
Estas ferramentas existem somente no Nodaro Cloud: `check_balance`, `credit_transactions`, `plan_edit`, `voice_changer_pro`, `voice_changer_pro_analyze`, `voice_changer_pro_export`, `create_explainer`, `create_launch_video`, `start_film_director` e `pro_3d_render`. O mesmo vale para as [ferramentas de espaço de trabalho](https://nodaro.ai/docs/mcp/tools/workspaces), as [ferramentas do Recast](https://nodaro.ai/docs/mcp/tools/recast), as [ferramentas de produção do Studio](https://nodaro.ai/docs/mcp/tools/studio-productions), as [ferramentas de pipeline](https://nodaro.ai/docs/mcp/tools/pipelines) e os montadores de UGC. As ferramentas de espaço de trabalho também exigem que as organizações estejam ativadas, e `pro_3d_render` só aparece enquanto o mecanismo de renderização dela estiver disponível.

## Frequently asked questions

### Quantas ferramentas o servidor MCP do Nodaro tem?

Cerca de 200 no Nodaro Cloud. A lista exata depende das permissões que você concedeu e da sua edição, porque uma ferramenta que você não pode usar fica fora da lista de ferramentas.

### Como o meu assistente recebe o resultado de uma geração?

Uma ferramenta de geração inicia um job e retorna o ID dele na hora. Os clientes que exibem MCP Apps mostram um cartão com o progresso em tempo real e o resultado; os outros clientes chamam get_job ou wait_for_job com esse ID.

### Por que o assistente só pode editar workflows do projeto mcp?

As ferramentas de workflow trabalham dentro de um único projeto chamado mcp, então um assistente nunca altera os seus próprios projetos. Ainda assim, ele pode ler qualquer workflow com export_workflow e importar uma cópia para o projeto mcp.

### Quais ferramentas são grátis?

As ferramentas de descoberta e de guia, como ping, list_models, get_node_skill, get_picker_catalog, list_shot_shapes e get_recipe, não custam nada. Toda ferramenta que gera, edita ou analisa mídia gasta créditos.