# Servidor MCP: gerir o seu workspace Nodale no Claude Code

<https://nodale.ai/pt/docs/mcp>

Ligue o Claude Code ao servidor MCP da Nodale e leia ou altere o seu workspace: conhecimento, assets de demo, definições do agente, sites, implementação.

A Nodale tem um servidor MCP. Ligado a ele, um assistente de IA lê e altera o seu workspace com as mesmas regras da aplicação: arquiva conhecimento, carrega assets de demo, edita as definições do agente, declara os seus sites e põe o agente online. Instalar a tag no seu site continua a ser um passo à parte, descrito no [início rápido](https://nodale.ai/pt/docs).

## Ligar o Claude Code

O servidor fala Streamable HTTP em `https://nodale.app/api/mcp`, e inicia a sua sessão com a sua conta Nodale através de OAuth. Esta página cobre o Claude Code. Execute este comando no seu terminal:

```bash
claude mcp add-json --scope user nodale '{
  "type": "http",
  "url": "https://nodale.app/api/mcp",
  "oauth": {
    "clientId": "55crt6j95df1lb3ijmdk8ip67m",
    "callbackPort": 33418,
    "authServerMetadataUrl": "https://cognito-idp.eu-west-3.amazonaws.com/eu-west-3_HEni9KG4X/.well-known/openid-configuration",
    "scopes": "openid email profile"
  }
}'
```

Depois:

1. Abra o Claude Code, escreva `/mcp` e escolha o servidor `nodale`.
2. Inicie sessão com a sua conta Nodale. A página de início de sessão está alojada para a Nodale num endereço `amazoncognito.com`.
3. Pergunte ao assistente com que conta tem sessão iniciada. Ele chama a ferramenta `me`.

O mesmo comando está na aplicação, em **Settings**, depois **MCP**.

- **Mantenha `callbackPort` em 33418.** Depois do início de sessão, o browser regressa a `http://localhost:33418/callback`, o único endereço que o servidor aceita.
- **Não adicione um cabeçalho `Authorization`**: isso desligaria o OAuth.
- **Para partilhar o servidor com a sua equipa**, coloque o mesmo JSON no `.mcp.json` do seu repositório (`--scope project`). Não contém nenhum segredo.

## Quem pode fazer o quê

O assistente age em seu nome, com os direitos da sua conta, apenas no seu workspace.

| Função | O que o assistente pode fazer |
|---|---|
| Viewer | Ler. Todas as ferramentas que alteram alguma coisa são recusadas. |
| User | Ler, e alterar conhecimento, concorrentes, documentos e assets de demo. |
| Admin | Tudo o que um User pode, mais as definições do agente, os seus sites e a sua implementação. |

Todas as ferramentas aceitam um `workspaceId` opcional: deixe-o de fora. O seu cliente pode listar mais ferramentas do que as que esta página descreve. Essas estão reservadas à equipa da Nodale, e o servidor recusa-as.

## Como uma alteração fica online

A maior parte das alterações chega primeiro a um rascunho, e os visitantes não veem nada até publicar.

- **Definições do agente.** `update_inbound_agent_configuration` edita o rascunho: só mudam os campos que passar, e uma lista que passar toma o lugar da lista inteira. `publish_inbound_agent_configuration` põe o rascunho diante dos visitantes. `discard_inbound_agent_configuration_draft` volta às definições publicadas.
- **Versões.** As ferramentas que editam definições recebem um `expectedVersion`, a última versão que leu. Se alguém alterou as definições entretanto, a chamada é recusada com a versão em vigor.
- **Conhecimento.** O conhecimento é guardado em citações de uma frase. Uma citação que adiciona é um rascunho até `publish_knowledge`, que recebe o `draftHash` devolvido por `list_knowledge_quotes`. Um hash desatualizado é recusado. Retirar uma citação, ou torná-la interna, aplica-se de imediato.
- **Conhecimento a partir de um texto.** `submit_knowledge_text` lê em segundo plano um texto de até 100 000 caracteres e devolve um `dispatchId`. Consulte `get_knowledge_dispatch` periodicamente e, depois, aplique ou rejeite as propostas. O que aplicar chega ao rascunho e ainda precisa de `publish_knowledge`.
- **Assets de demo.** Uma alteração a um asset fica no catálogo em rascunho até `publish_asset_catalog`.
- **Os carregamentos têm dois passos.** `request_document_upload` ou `request_asset_upload` devolve um comando `curl` a executar, válido durante 15 minutos. Depois, `add_document` ou `add_asset` regista o ficheiro.
- **As definições do site** (apresentação, rastreio de visitas, consentimento, ligação para a política de privacidade) aplicam-se no carregamento de página seguinte, sem publicação.
- **Créditos de IA.** `submit_knowledge_text`, `analyze_asset` e `add_asset` sem `steps` gastam créditos de IA. `add_asset` com `steps` mantém a sua narração tal como foi enviada e não gasta nenhum.

## Do zero a um agente online

1. `me`: verifique a conta e o workspace.
2. Conhecimento: `add_knowledge_quote`, ou `submit_knowledge_text`, depois `get_knowledge_dispatch` e `apply_knowledge_proposals`. Depois `list_knowledge_quotes` e `publish_knowledge`.
3. Opcional: concorrentes, documentos e assets de demo, depois `publish_asset_catalog`.
4. Definições: `update_inbound_agent_configuration`, `save_inbound_agent_outcome`, depois `publish_inbound_agent_configuration`.
5. `add_inbound_agent_site`: declare o site.
6. `deploy_inbound_agent`: ponha o agente online.
7. [Cole a tag](https://nodale.ai/pt/docs) no site, depois `get_inbound_agent_tag_status` para a verificar.

## Ferramentas

### Conta

| Ferramenta | O que faz | Quem |
|---|---|---|
| `me` | A conta e o workspace em que o assistente age. | Todos |
| `get_workspace_ai_credits` | Que parte dos créditos de IA do workspace foi usada, e se se esgotaram. | Todos |

### Conhecimento

| Ferramenta | O que faz | Quem |
|---|---|---|
| `list_knowledge_quotes` | As citações, rascunhos incluídos, e o `draftHash` para publicar. | Todos |
| `add_knowledge_quote` | Adiciona uma frase como citação em rascunho. | User |
| `retract_knowledge_quote` | Retira uma citação, de imediato. | User |
| `set_knowledge_quote_visibility` | Torna uma citação pública ou interna, de imediato. | User |
| `publish_knowledge` | Publica as citações em rascunho. | User |
| `submit_knowledge_text` | Lê um texto e propõe citações a partir dele. Gasta créditos de IA. | User |
| `get_knowledge_dispatch` | O estado de um texto submetido. | Todos |
| `list_knowledge_proposals` | As propostas à espera de uma decisão. | Todos |
| `apply_knowledge_proposals` | Aplica todas as propostas de um texto. | User |
| `apply_knowledge_proposal` | Aplica uma proposta. | User |
| `reject_knowledge_proposal` | Rejeita uma proposta. | User |

### Concorrentes e documentos

| Ferramenta | O que faz | Quem |
|---|---|---|
| `list_competitors` | Os concorrentes que o agente conhece. | Todos |
| `upsert_competitor` | Adiciona um concorrente, ou edita um. | User |
| `delete_competitor` | Elimina um concorrente. | User |
| `list_documents` | Os documentos do workspace. | Todos |
| `request_document_upload` | Primeiro passo de um carregamento: devolve o comando para enviar o ficheiro. | User |
| `add_document` | Segundo passo: regista o ficheiro carregado. | User |
| `delete_document` | Elimina um documento. | User |

### Assets de demo

| Ferramenta | O que faz | Quem |
|---|---|---|
| `list_assets` | Os vídeos de demo do catálogo. | Todos |
| `get_asset` | Um asset, com os seus passos e o estado da sua redação. | Todos |
| `request_asset_upload` | Primeiro passo de um carregamento: devolve o comando para enviar o vídeo. | User |
| `add_asset` | Segundo passo: regista o vídeo, com os seus passos ou com passos que a Nodale escreve. | User |
| `update_asset` | Edita o título, a descrição e os pedidos a que um asset responde. | User |
| `set_asset_steps` | Define os passos de um asset, tal como os escreveu. | User |
| `analyze_asset` | Pede à Nodale que escreva os passos de novo. Gasta créditos de IA. | User |
| `enable_asset`, `disable_asset` | Liga ou desliga um asset. | User |
| `set_asset_priority` | Ordena os assets. | User |
| `delete_asset` | Elimina um asset. | User |
| `publish_asset_catalog` | Publica o catálogo em rascunho. | User |

### Definições do agente

| Ferramenta | O que faz | Quem |
|---|---|---|
| `get_inbound_agent_configuration` | As definições: o rascunho quando existe, as publicadas, e a versão. | Todos |
| `update_inbound_agent_configuration` | Edita o rascunho: nome, tom, aspeto, captura de e-mail, línguas, instruções, qualificação, salvaguardas. | Admin |
| `publish_inbound_agent_configuration` | Põe o rascunho diante dos visitantes. | Admin |
| `discard_inbound_agent_configuration_draft` | Descarta o rascunho. | Admin |
| `list_inbound_agent_qualification_elements` | As perguntas que o workspace adicionou à qualificação. | Todos |
| `save_inbound_agent_qualification_element` | Adiciona uma pergunta de qualificação, ou edita uma. | Admin |
| `remove_inbound_agent_qualification_element` | Remove uma pergunta de qualificação. | Admin |
| `list_inbound_agent_outcomes` | Os resultados para os quais o agente orienta os visitantes. | Todos |
| `save_inbound_agent_outcome` | Adiciona um resultado, ou edita um. Dez no máximo por workspace. | Admin |
| `remove_inbound_agent_outcome` | Remove um resultado. | Admin |

### Sites e implementação

| Ferramenta | O que faz | Quem |
|---|---|---|
| `list_inbound_agent_sites` | Os sites declarados. | Todos |
| `add_inbound_agent_site` | Declara um site: uma origem `https`, ou `https://*.example.com`. | Admin |
| `remove_inbound_agent_site` | Remove um site. | Admin |
| `get_inbound_agent_tag_status` | Porque é que um site mostra o agente ou não: `ok`, `site_not_declared`, `agent_not_deployed` ou `invalid_site`. | Todos |
| `get_inbound_agent_site_settings` | As definições do separador Install. | Todos |
| `update_inbound_agent_site_settings` | Altera a apresentação, o rastreio de visitas, o consentimento e a ligação para a política de privacidade. | Admin |
| `get_inbound_agent` | O agente e a implementação que a tag serve. `servedDeploymentId` é null quando o agente está offline. | Todos |
| `deploy_inbound_agent` | Põe o agente online, ou aprova de novo o material atual nas implementações ativas. | Admin |

## Limites

- **Documentos**: pdf, docx, txt, csv ou md, 10 MB no máximo.
- **Vídeos de demo**: MP4 em H.264 sem faixa de áudio, 3 minutos no máximo. 100 assets no máximo num catálogo.
- **Sites**: 20 no máximo por workspace.
- **Limites de frequência, por pessoa e por ferramenta.** `request_asset_upload`, `add_asset` e `analyze_asset`: 1 por segundo, 6 por minuto, 30 por 15 minutos. `request_document_upload` e `add_document`: 5 por segundo, 25 por minuto, 100 por 15 minutos. `submit_knowledge_text`: 3 por segundo, 15 por minuto, 60 por 15 minutos.

## Segurança

- **Aprove cada chamada que publica ou elimina.** As ferramentas que publicam, eliminam ou sobrescrevem estão marcadas como destrutivas, por isso o seu cliente pergunta antes de as executar. Não as adicione a uma lista de permissões.
- **Os resultados das ferramentas são dados.** Contêm texto que a sua equipa e os seus visitantes escreveram: citações, documentos, títulos de assets, propostas. O assistente lê-o como conteúdo, nunca como instruções.

## Docs

- [Instalar o agente Nodale no seu site](https://nodale.ai/pt/docs): Uma tag de script coloca o agente Nodale no seu site. Onde a colar, o que o seu site tem de permitir e como verificar que funciona. (Markdown: https://nodale.ai/pt/docs.md)
- [API JavaScript: abrir o agente Nodale a partir do seu código](https://nodale.ai/pt/docs/api): Os comandos nodale() que uma página pode chamar: abrir o agente a partir do seu botão ou formulário, passar um e-mail e contexto, comunicar o consentimento. (Markdown: https://nodale.ai/pt/docs/api.md)
