# Solução de problemas

> Resolva problemas comuns do Nodaro MCP, de URL errada, login com falha e ferramentas ausentes a jobs com falha, uploads e códigos como client_not_allowed.

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

Esta página lista os problemas mais comuns com o **servidor MCP do Nodaro** e como resolvê-los. Ela cobre erros de conexão e de login, ferramentas que não aparecem, jobs que falham ou parecem travados, uploads e os códigos de erro que as ferramentas retornam. Comece pela seção que corresponde ao que você vê.

## Conexão e login
### O cliente mostra um erro de OAuth quando você adiciona o conector
1. Confira se a URL é exatamente `https://mcp.nodaro.ai/mcp`, sem barra no final.
2. Confira se `mcp.nodaro.ai` é resolvido na sua rede.
3. Confira o documento de descoberta. Este comando deve retornar `200` com JSON:

```bash
curl https://mcp.nodaro.ai/.well-known/oauth-protected-resource
```

O mesmo host também serve `/.well-known/oauth-authorization-server`, que também deve retornar `200` com JSON.

### O login nunca termina, ou a URL está errada
O servidor só responde em `https://mcp.nodaro.ai/mcp`. Dois erros comuns falham antes de o login chegar ao Nodaro:

- **`https://api.nodaro.ai/mcp`**: esse domínio não existe, então a conexão falha na consulta do nome.
- **`https://app.nodaro.ai/mcp`**: esta é a página web do MCP, não o servidor. Um `POST` nela retorna `405` com o código de erro `wrong_mcp_host`, que informa a URL correta.

O Claude não permite editar a URL de um conector. Exclua o conector com problema e adicione-o de novo com `https://mcp.nodaro.ai/mcp`.

### A tela de consentimento mostra um aviso laranja sobre o nome do cliente
Isso é esperado. Um cliente que se registra sozinho escolhe o próprio nome, como “Claude”, e o Nodaro não verifica esse nome. O aviso lembra você de conferir se o app que pede acesso é o mesmo que você está configurando antes de clicar em **Permitir**.

### O registro falha com “Client not allowed”
Seu cliente se registrou com um nome que não está na lista de clientes aceitos. Você pode:

- Usar um cliente compatível, como Claude, ChatGPT, Cursor, Cline, Continue ou Goose.
- Registrar um app de desenvolvedor em [app.nodaro.ai/settings/developer-apps](https://app.nodaro.ai/settings/developer-apps) e usar o ID do cliente e o segredo dele. Veja [Seu próprio cliente](https://nodaro.ai/docs/mcp/connect/custom-client).
- Na sua própria instância, pedir ao operador que adicione o nome do cliente a `MCP_DCR_ALLOWLIST` ou que defina `MCP_DYNAMIC_REGISTRATION=open`. Veja [MCP em uma instalação self-hosted](https://nodaro.ai/docs/self-hosting/mcp).

### O assistente parou de funcionar depois de um tempo
O acesso dura 90 dias, e não há refresh tokens. Quando ele expira, as chamadas retornam `401`. Faça login de novo pelo seu cliente ou remova o conector e adicione-o de novo.

### Execuções que você não iniciou mostram “via MCP”
Um cliente MCP conectado as iniciou em seu nome. Abra **Configurações › Apps conectados**, em [app.nodaro.ai/settings/connected-apps](https://app.nodaro.ai/settings/connected-apps). A página lista todos os apps e assistentes de IA com acesso à sua conta, com a data em que cada um foi conectado e usado pela última vez.

- Um assistente que se registrou sozinho aparece como “Assistente de IA (MCP) — o nome foi definido pelo assistente”. O Nodaro não verificou esse nome.
- Para remover um app que você não reconhece, clique em **Revogar acesso** e confirme. O acesso dele termina na hora, e os tokens dele param de funcionar.

## Ferramentas ausentes
### O cliente está conectado, mas não mostra nenhuma ferramenta, ou só algumas
Uma ferramenta cuja permissão você não concedeu fica totalmente de fora da lista de ferramentas. Remova o conector, adicione-o de novo e conceda todas as permissões na tela de consentimento. Algumas ferramentas também precisam de mais de uma permissão:

- **As ferramentas de geração do Studio** precisam de `workflows:write` e de `workflows:execute`. Com só uma delas, nenhuma dessas ferramentas aparece.
- **As ferramentas de espaço de trabalho** precisam de `workspaces:read` e `workspaces:write`, que as conexões autorizadas antes de os espaços de trabalho existirem não têm. Conecte-se de novo para obtê-las.

[Permissões](https://nodaro.ai/docs/mcp/tools#permissions) lista qual ferramenta precisa de qual permissão.

### Uma ferramenta da documentação não aparece na sua lista
Algumas ferramentas só existem no Nodaro Cloud, como as ferramentas de pipeline, de produções do Studio, de recast e de espaço de trabalho, `start_film_director`, `create_explainer`, `plan_edit`, `voice_changer_pro`, `pro_3d_render` e as ferramentas de créditos. 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. Veja [Ferramentas só no Nodaro Cloud](https://nodaro.ai/docs/mcp/tools#tools-only-on-nodaro-cloud).

## Jobs e resultados
### Uma geração falhou
Peça ao assistente que chame `get_job` ou `diagnose_run` com o ID do job. Leia `retryable` e `guidance`: quando `retryable` é `false`, o mesmo pedido vai falhar de novo se nada mudar; por isso, mude as configurações ou a entrada. Quando `suggestedProvider` estiver presente, execute o mesmo prompt e as mesmas referências nesse modelo. [Quando um job falha](https://nodaro.ai/docs/mcp/tools/jobs#when-a-job-fails) traz os detalhes. Os créditos reservados para um job com falha são reembolsados, exceto depois de uma falha no pós-processamento.

### Um job mostra `pending_review`
A implantação retém os resultados para uma pessoa revisar. O job ainda está em andamento, não falhou. Continue verificando o job e não o execute de novo: uma duplicata também ficaria retida.

### `wait_for_job` retorna `timeout`
Isso não é um erro. O job ainda estava em execução quando a espera terminou, depois de no máximo 120 segundos. Chame `wait_for_job` de novo ou consulte `get_job` periodicamente, a cada 5 a 10 segundos. Os vídeos costumam levar de 2 a 10 minutos.

### O cartão do resultado não aparece
Os cartões precisam de um cliente que exiba MCP Apps, como o Claude na web. Em outros clientes, peça ao assistente que verifique o job com `get_job`. O resultado é sempre salvo na sua biblioteca.

### Uma execução foi cobrada duas vezes depois de um timeout
Passe um `client_request_id` em `run_workflow`, `run_app`, `run_component` e nas ferramentas de produção, e reutilize o mesmo valor quando repetir a chamada. Assim, o Nodaro retorna a primeira execução em vez de iniciar e cobrar uma segunda.

## Uploads
### `prepare_image_upload` falha no Claude na web
O upload pré-assinado precisa de um cliente que consiga acessar o host de armazenamento por um shell, como Cursor, Cline, Claude Desktop ou Claude Code. No Claude na web e no Android, use `upload_image_widget`, ou `request_image_upload`, que dá a você um link para abrir no navegador. Veja [Ferramentas de upload](https://nodaro.ai/docs/mcp/tools/uploads).

## Workflows
### `update_workflow_json` diz que o workflow foi modificado
Alguém alterou o workflow depois que você o leu. Leia-o de novo com `get_workflow_json` e envie a alteração de novo com a nova versão.

### Uma configuração que você enviou não é a que foi salva
Um modelo não aceita todas as proporções, resoluções ou qualidades. O Nodaro troca um valor não suportado por um suportado, ou o remove, e lista cada mudança em `adjustments`. Não envie o valor original de novo; escolha um modelo que o aceite, usando `list_models`.

### O canvas do Film Director continua vazio
A skill adiciona os nós de uma etapa de uma só vez, depois que você aprova a etapa. Espere o Claude dizer que os adicionou e então atualize a página. Mais soluções estão em [Film Director](https://nodaro.ai/docs/mcp/film-director#if-something-goes-wrong).

## Códigos de erro
| Código | Ferramenta | O que significa | O que fazer |
| --- | --- | --- | --- |
| `wrong_mcp_host` | O servidor | O cliente chamou a página web em `app.nodaro.ai/mcp` | Use `https://mcp.nodaro.ai/mcp` |
| `client_not_allowed` | Registro | O nome do cliente não é aceito | Use um cliente compatível ou um app de desenvolvedor |
| `too_many_open_registrations` | Registro | Registros não usados demais de um mesmo cliente no modo aberto | Use os registros que você já tem ou espere |
| `dcr_disabled` | Registro | A instância desativou o autorregistro | Use um ID de cliente e um segredo fornecidos pelo operador |
| `voice_not_found` | Ferramentas de fala | O ID da voz não existe | Use o nome de uma voz pronta ou uma voz que você clonou |
| `advanced_mode_unsupported` | Ferramentas de prompt e de texto | `advanced_mode` foi usado com um modelo que não é Gemini | Escolha um modelo Gemini ou desative o modo avançado |
| `locked_field` | `run_app` | `inputOverrides` tentou mudar para onde vai uma saída | Deixe os destinos como o app os define |
| `portrait_required` | `generate_character` | O personagem não tem um retrato aprovado | Aprove um retrato com `approve_portrait` primeiro |
| `main_image_required` | Ferramentas de locais, objetos e criaturas | Não há uma imagem principal aprovada | Aprove uma imagem principal primeiro |
| `candidate_object_mismatch`, `candidate_creature_mismatch` | Ferramentas de aprovação | O candidato não foi gerado para este objeto ou criatura | Aprove um candidato feito para ele |
| `scene_overlap` | `resolve_shot_sequence` | Duas cenas têm revelações no mesmo trecho de tempo | Mantenha as deixas de cada cena antes das deixas da cena seguinte |
| `not_available` | Ferramentas de produções do Studio | A implantação não oferece produções do Studio | Não tente de novo; o recurso não está disponível ali |
| `studio_preview_unavailable` | `edit_studio_production` | A implantação não consegue pré-visualizar um lote | Nada foi enviado; decida com o usuário se o lote deve ser aplicado sem prévia |
| `not_finished` | `import_studio_production` | O job do plano ainda está em execução | Espere o job terminar e depois importe |
| `cloud_only_feature` | `combine_videos` | `smart_cut` foi usado em uma instalação self-hosted | Junte os clipes sem `smart_cut` |
| `payer_balance_jwt_only` | `check_balance`, `credit_transactions` | A conta de cobrança compartilhada da implantação não pode ser lida por um cliente conectado | Veja o saldo no app |

## Frequently asked questions

### Por que meu cliente mostra o Nodaro como conectado, mas não lista nenhuma ferramenta?

As permissões concedidas na tela de consentimento não cobrem as ferramentas. Remova o conector, adicione-o de novo e conceda todas as permissões.

### Qual URL devo usar para o servidor MCP do Nodaro?

Exatamente https://mcp.nodaro.ai/mcp, sem barra no final. api.nodaro.ai não existe, e app.nodaro.ai/mcp é uma página web, não o servidor.

### O que significa client_not_allowed?

Seu cliente se registrou com um nome que não está na lista de clientes aceitos. Use um cliente compatível ou registre um app de desenvolvedor nas suas configurações do Nodaro e use o ID do cliente e o segredo dele.

### Meu assistente parou de funcionar depois de alguns meses. Por quê?

O acesso de um cliente MCP dura 90 dias, e não há refresh tokens. Faça login de novo pelo seu cliente ou remova o conector e adicione-o de novo.

### Vejo execuções marcadas com via MCP que eu não iniciei. O que devo fazer?

Um cliente conectado as iniciou em seu nome. Abra Configurações › Apps conectados, em app.nodaro.ai/settings/connected-apps, revise todos os apps e assistentes com acesso à sua conta e revogue os que você não reconhece. A revogação encerra o acesso na hora.