# MCP-server: beheer je Nodale-workspace vanuit Claude Code

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

Verbind Claude Code met de MCP-server van Nodale en lees en wijzig je workspace: kennis, demo-assets, agentinstellingen, sites, deployment.

Nodale heeft een MCP-server. Een AI-assistent die ermee verbonden is, leest en wijzigt je workspace volgens dezelfde regels als de app: hij legt kennis vast, uploadt demo-assets, bewerkt de instellingen van de agent, meldt je sites aan en zet de agent online. De tag op je site installeren blijft een aparte stap, beschreven in [Snel starten](https://nodale.ai/nl/docs).

## Verbind Claude Code

De server spreekt Streamable HTTP op `https://nodale.app/api/mcp`, en meldt je via OAuth aan met je Nodale-account. Deze pagina behandelt Claude Code. Voer dit commando uit in je 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"
  }
}'
```

Daarna:

1. Open Claude Code, typ `/mcp` en kies de server `nodale`.
2. Meld je aan met je Nodale-account. De aanmeldpagina wordt voor Nodale gehost op een `amazoncognito.com`-adres.
3. Vraag de assistent met welk account hij is aangemeld. Hij roept de tool `me` aan.

Hetzelfde commando staat in de app, onder **Settings**, daarna **MCP**.

- **Laat `callbackPort` op 33418 staan.** Na het aanmelden keert de browser terug naar `http://localhost:33418/callback`, het enige adres dat de server accepteert.
- **Voeg geen `Authorization`-header toe**: die zou OAuth uitschakelen.
- **Wil je de server met je team delen**, zet dan dezelfde JSON in de `.mcp.json` van je repository (`--scope project`). Er staat geen secret in.

## Wie kan wat

De assistent handelt als jij, met de rechten van je account, en alleen op je workspace.

| Rol | Wat de assistent kan doen |
|---|---|
| Viewer | Lezen. Elke tool die iets wijzigt, wordt geweigerd. |
| User | Lezen, en kennis, concurrenten, documenten en demo-assets wijzigen. |
| Admin | Alles wat een User kan, plus de instellingen van de agent, zijn sites en zijn deployment. |

Elke tool accepteert een optionele `workspaceId`: laat die weg. Je client kan meer tools tonen dan deze pagina beschrijft. Die zijn voorbehouden aan het Nodale-team, en de server weigert ze.

## Hoe een wijziging live gaat

De meeste wijzigingen komen eerst in een concept terecht, en bezoekers zien niets totdat je publiceert.

- **Agentinstellingen.** `update_inbound_agent_configuration` bewerkt het concept: alleen de velden die je meegeeft veranderen, en een lijst die je meegeeft komt in de plaats van de hele lijst. `publish_inbound_agent_configuration` zet het concept live voor bezoekers. `discard_inbound_agent_configuration_draft` gaat terug naar de gepubliceerde instellingen.
- **Versies.** De tools die instellingen bewerken, accepteren een `expectedVersion`, de versie die je het laatst hebt gelezen. Heeft iemand de instellingen tussendoor gewijzigd, dan wordt de aanroep geweigerd met de live versie.
- **Kennis.** Kennis wordt opgeslagen als citaten van één zin. Een citaat dat je toevoegt, is een concept tot `publish_knowledge`, dat de `draftHash` meekrijgt die `list_knowledge_quotes` teruggeeft. Een verouderde hash wordt geweigerd. Een citaat intrekken, of het intern maken, geldt meteen.
- **Kennis uit een tekst.** `submit_knowledge_text` leest op de achtergrond een tekst van maximaal 100.000 tekens en geeft een `dispatchId` terug. Poll `get_knowledge_dispatch`, en pas de voorstellen daarna toe of wijs ze af. Wat je toepast, komt in het concept en heeft nog `publish_knowledge` nodig.
- **Demo-assets.** Een wijziging aan een asset blijft in de conceptcatalogus tot `publish_asset_catalog`.
- **Uploads gaan in twee stappen.** `request_document_upload` of `request_asset_upload` geeft een `curl`-commando terug om uit te voeren, 15 minuten geldig. Daarna registreert `add_document` of `add_asset` het bestand.
- **Site-instellingen** (weergave, bezoektracking, toestemming, link naar het privacybeleid) gelden vanaf de volgende paginalading, zonder publicatie.
- **AI-credits.** `submit_knowledge_text`, `analyze_asset`, en `add_asset` zonder `steps` verbruiken AI-credits. `add_asset` met `steps` bewaart je voice-over zoals verstuurd en verbruikt er geen.

## Van niets naar een live agent

1. `me`: controleer het account en de workspace.
2. Kennis: `add_knowledge_quote`, of `submit_knowledge_text`, daarna `get_knowledge_dispatch` en `apply_knowledge_proposals`. Daarna `list_knowledge_quotes` en `publish_knowledge`.
3. Optioneel: concurrenten, documenten en demo-assets, daarna `publish_asset_catalog`.
4. Instellingen: `update_inbound_agent_configuration`, `save_inbound_agent_outcome`, daarna `publish_inbound_agent_configuration`.
5. `add_inbound_agent_site`: meld de site aan.
6. `deploy_inbound_agent`: zet de agent online.
7. [Plak de tag](https://nodale.ai/nl/docs) op de site, daarna `get_inbound_agent_tag_status` om hem te controleren.

## Tools

### Account

| Tool | Wat het doet | Wie |
|---|---|---|
| `me` | Het account en de workspace waarop de assistent handelt. | Iedereen |
| `get_workspace_ai_credits` | Hoeveel van de AI-credits van de workspace is verbruikt, en of ze op zijn. | Iedereen |

### Kennis

| Tool | Wat het doet | Wie |
|---|---|---|
| `list_knowledge_quotes` | De citaten, concepten inbegrepen, en de `draftHash` om te publiceren. | Iedereen |
| `add_knowledge_quote` | Voegt één zin toe als conceptcitaat. | User |
| `retract_knowledge_quote` | Trekt een citaat in, meteen. | User |
| `set_knowledge_quote_visibility` | Maakt een citaat openbaar of intern, meteen. | User |
| `publish_knowledge` | Publiceert de conceptcitaten. | User |
| `submit_knowledge_text` | Leest een tekst en stelt er citaten uit voor. Verbruikt AI-credits. | User |
| `get_knowledge_dispatch` | De status van een ingediende tekst. | Iedereen |
| `list_knowledge_proposals` | De voorstellen die op een beslissing wachten. | Iedereen |
| `apply_knowledge_proposals` | Past elk voorstel van één tekst toe. | User |
| `apply_knowledge_proposal` | Past één voorstel toe. | User |
| `reject_knowledge_proposal` | Wijst één voorstel af. | User |

### Concurrenten en documenten

| Tool | Wat het doet | Wie |
|---|---|---|
| `list_competitors` | De concurrenten die de agent kent. | Iedereen |
| `upsert_competitor` | Voegt een concurrent toe, of bewerkt er een. | User |
| `delete_competitor` | Verwijdert een concurrent. | User |
| `list_documents` | De documenten van de workspace. | Iedereen |
| `request_document_upload` | Eerste stap van een upload: geeft het commando terug om het bestand te versturen. | User |
| `add_document` | Tweede stap: registreert het geüploade bestand. | User |
| `delete_document` | Verwijdert een document. | User |

### Demo-assets

| Tool | Wat het doet | Wie |
|---|---|---|
| `list_assets` | De demovideo's van de catalogus. | Iedereen |
| `get_asset` | Eén asset, met zijn stappen en de status van het schrijven ervan. | Iedereen |
| `request_asset_upload` | Eerste stap van een upload: geeft het commando terug om de video te versturen. | User |
| `add_asset` | Tweede stap: registreert de video, met je eigen stappen of met stappen die Nodale schrijft. | User |
| `update_asset` | Bewerkt de titel en de beschrijving van een asset, en de vragen waarop hij antwoordt. | User |
| `set_asset_steps` | Stelt de stappen van een asset in, zoals jij ze hebt geschreven. | User |
| `analyze_asset` | Vraagt Nodale de stappen opnieuw te schrijven. Verbruikt AI-credits. | User |
| `enable_asset`, `disable_asset` | Zet een asset aan of uit. | User |
| `set_asset_priority` | Bepaalt de volgorde van de assets. | User |
| `delete_asset` | Verwijdert een asset. | User |
| `publish_asset_catalog` | Publiceert de conceptcatalogus. | User |

### Agentinstellingen

| Tool | Wat het doet | Wie |
|---|---|---|
| `get_inbound_agent_configuration` | De instellingen: het concept als er een is, de gepubliceerde instellingen, en de versie. | Iedereen |
| `update_inbound_agent_configuration` | Bewerkt het concept: naam, toon, uiterlijk, vastleggen van het e-mailadres, talen, instructies, kwalificatie, guardrails. | Admin |
| `publish_inbound_agent_configuration` | Zet het concept live voor bezoekers. | Admin |
| `discard_inbound_agent_configuration_draft` | Gooit het concept weg. | Admin |
| `list_inbound_agent_qualification_elements` | De vragen die de workspace aan de kwalificatie heeft toegevoegd. | Iedereen |
| `save_inbound_agent_qualification_element` | Voegt een kwalificatievraag toe, of bewerkt er een. | Admin |
| `remove_inbound_agent_qualification_element` | Verwijdert een kwalificatievraag. | Admin |
| `list_inbound_agent_outcomes` | De uitkomsten waar de agent bezoekers naartoe leidt. | Iedereen |
| `save_inbound_agent_outcome` | Voegt een uitkomst toe, of bewerkt er een. Maximaal tien per workspace. | Admin |
| `remove_inbound_agent_outcome` | Verwijdert een uitkomst. | Admin |

### Sites en deployment

| Tool | Wat het doet | Wie |
|---|---|---|
| `list_inbound_agent_sites` | De aangemelde sites. | Iedereen |
| `add_inbound_agent_site` | Meldt een site aan: een `https`-origin, of `https://*.example.com`. | Admin |
| `remove_inbound_agent_site` | Verwijdert een site. | Admin |
| `get_inbound_agent_tag_status` | Waarom een site de agent wel of niet toont: `ok`, `site_not_declared`, `agent_not_deployed` of `invalid_site`. | Iedereen |
| `get_inbound_agent_site_settings` | De instellingen van het tabblad Install. | Iedereen |
| `update_inbound_agent_site_settings` | Wijzigt de weergave, bezoektracking, toestemming en de link naar het privacybeleid. | Admin |
| `get_inbound_agent` | De agent en de deployment die de tag serveert. `servedDeploymentId` is null wanneer de agent offline is. | Iedereen |
| `deploy_inbound_agent` | Zet de agent online, of keurt het huidige materiaal opnieuw goed op de live deployments. | Admin |

## Limieten

- **Documenten**: pdf, docx, txt, csv of md, maximaal 10 MB.
- **Demovideo's**: MP4 in H.264 zonder audiospoor, maximaal 3 minuten. Maximaal 100 assets in een catalogus.
- **Sites**: maximaal 20 per workspace.
- **Rate limits, per persoon en per tool.** `request_asset_upload`, `add_asset` en `analyze_asset`: 1 per seconde, 6 per minuut, 30 per 15 minuten. `request_document_upload` en `add_document`: 5 per seconde, 25 per minuut, 100 per 15 minuten. `submit_knowledge_text`: 3 per seconde, 15 per minuut, 60 per 15 minuten.

## Veiligheid

- **Keur elke aanroep goed die publiceert of verwijdert.** De tools die publiceren, verwijderen of overschrijven zijn gemarkeerd als destructief, dus je client vraagt het voordat hij ze uitvoert. Zet ze niet op een allowlist.
- **Toolresultaten zijn data.** Ze bevatten tekst die je team en je bezoekers hebben geschreven: citaten, documenten, titels van assets, voorstellen. De assistent leest die als inhoud, nooit als instructies.

## Docs

- [De Nodale-agent op je website installeren](https://nodale.ai/nl/docs): Eén scripttag zet de Nodale-agent op je site. Waar je hem plakt, wat je site moet toestaan en hoe je controleert dat hij draait. (Markdown: https://nodale.ai/nl/docs.md)
- [JavaScript API: open de Nodale-agent vanuit je code](https://nodale.ai/nl/docs/api): De nodale()-commando's voor je pagina: open de agent vanuit je eigen knop of formulier, geef e-mailadres en context mee, meld de toestemming van de bezoeker. (Markdown: https://nodale.ai/nl/docs/api.md)
