<!-- AI-assistent (MCP) -->
<!-- canonical: https://yres.eu/nl/wiki/frontend/ai-assistent-mcp -->
# AI-assistent (MCP)

:::note Vanaf v1.57
De MCP-server en personal access tokens zijn beschikbaar vanaf release 1.57.
:::

MCP (Model Context Protocol) is een open standaard waarmee een AI-assistent veilig met andere software kan
werken. Elke Yres-organisatie heeft een eigen MCP-server. Een assistent die MCP ondersteunt, zoals Claude
Code of VS Code, kan daarmee je omgevingen en bronnen opvragen, used tables toevoegen of
aanpassen, changes en projecten beheren, een bron laten laden en de monitoring bekijken. Je vraagt het in
gewone taal; de assistent kiest zelf de juiste tools.

## Wat je ermee kunt

De assistent gebruikt de tools hieronder. De namen in de rechterkolom zijn de toolnamen die je assistent
te zien krijgt.

| Onderwerp | Wat de assistent kan doen | Tools |
|---|---|---|
| Omgevingen | De omgevingen van je organisatie opvragen (dev, test, prod). | `list-environments-tool` |
| Bronnen | Je databronnen opvragen, met details zoals de installatiestatus en welke optionele tabelinstellingen de bron ondersteunt. | `list-data-sources-tool`, `get-data-source-tool` |
| Bronnen | De tags van een bron bijwerken. | `update-data-source-tags-tool` |
| Tabellen bekijken | De used tables van een bron opvragen, en van één tabel de volledige laadconfiguratie. | `list-used-tables-tool`, `get-used-table-tool` |
| Tabellen kiezen | Bekijken welke brontabellen nog niet geladen worden, welke kolommen een brontabel heeft en welke sleutel Yres voorstelt. | `list-unused-tables-tool`, `get-data-source-dictionary-tool`, `predict-key-columns-tool` |
| Tabellen toevoegen | Een brontabel als used table toevoegen, of een endpoint van een REST-bron. | `create-used-table-tool`, `create-used-rest-service-table-tool` |
| Tabellen aanpassen | De laadconfiguratie van een bestaande used table wijzigen, zoals het laadtype, de kolommen of de sleutel. | `update-used-table-tool` |
| Changes | Changes opvragen, aanmaken, bijwerken, naar een ander project verplaatsen of verwijderen zolang ze open staan. | `list-changes-tool`, `create-change-tool`, `update-change-tool`, `move-change-to-project-tool`, `delete-change-tool` |
| Projecten | Projecten opvragen, aanmaken, bijwerken of verwijderen zolang ze open staan. | `list-projects-tool`, `create-project-tool`, `update-project-tool`, `delete-project-tool` |
| Laden | Een bron laten laden: één tabel of alle used tables van de bron. | `load-data-source-data-tool` |
| Metadata | De metadata van een bron opnieuw laten inlezen, zodat nieuwe tabellen en kolommen zichtbaar worden. | `refresh-data-source-metadata-tool` |
| Voortgang volgen | De status van een gestarte pipeline-run of van een achtergrondproces volgen. | `get-pipeline-run-tool`, `get-monitor-tool` |
| Monitoring | De laatste laadactie per tabel bekijken, en per tabel het resultaat van een load die de assistent heeft gestart. | `list-latest-loads-tool`, `get-load-tool` |

Daarnaast biedt de server twee kant-en-klare prompts: **Add Used Table** en **Update Used Table**. Ze
leiden de assistent stap voor stap door het toevoegen of aanpassen van een used table: bron en change
kiezen, kolommen en sleutel bepalen, het laadtype afstemmen en het resultaat controleren. In een client
die prompts ondersteunt, kies je ze uit de lijst van de server.

Changes en projecten afsluiten, releasen en installeren doe je in de webapp. Ook een laadfilter op een
used table en het aanpassen van REST-tabellen blijven in de webapp.

## Verbinden

Je hebt twee dingen nodig: het adres van de MCP-server en een personal access token.

1. Open in de webapp het gebruikersmenu (het icoon met je initialen) en kies **API tokens & MCP**.
2. Klik op **Create**, geef het token een naam en kies eventueel een vervaldatum. Kopieer het token direct
   met **Copy token**: het wordt maar één keer getoond. Zie ook
   [Account](https://yres.eu/nl/wiki/frontend/account#api-tokens--mcp-vanaf-v157).
3. Klik op **MCP setup**. Dit venster toont een kant-en-klare configuratie voor **VS Code** en voor
   **Claude Code**, die je kunt kopiëren of downloaden.

![Het venster MCP server setup met de tabbladen VS Code en Claude Code en een kant-en-klare mcp.json met het adres van de MCP-server.](https://yres.eu/nl/wiki/img/screens/user-tokens-mcp-setup.png)

*Het venster **MCP server setup**: kies het tabblad van je client en kopieer of download de configuratie. Het organisatie-UUID staat al in het adres.*

Open je **MCP setup** binnen een organisatie, dan staat het organisatie-UUID al in het adres. Het adres
heeft de vorm:

```text
https://api.yres.app/mcp/organization/<organisatie-uuid>
```

De server heet in de configuratie `yres-organization` en gebruikt HTTP-transport. Het token gaat mee als
`Authorization: Bearer <token>`.

### Claude Code

Sla de configuratie op als `.mcp.json` in de hoofdmap van je project:

```json
{
  "mcpServers": {
    "yres-organization": {
      "type": "http",
      "url": "https://api.yres.app/mcp/organization/<organisatie-uuid>",
      "headers": {
        "Authorization": "Bearer ${YRES_MCP_TOKEN}"
      }
    }
  }
}
```

Claude Code vult `${YRES_MCP_TOKEN}` in vanuit je omgevingsvariabelen. Zet je token dus in die variabele.
Je kunt de server ook vanaf de opdrachtregel toevoegen:

```bash
claude mcp add --scope project --transport http yres-organization https://api.yres.app/mcp/organization/<organisatie-uuid> --header "Authorization: Bearer <your-token>"
```

### VS Code

Sla de configuratie op als `.vscode/mcp.json` in je project. VS Code vraagt de eerste keer dat de server
start om het token:

```json
{
  "servers": {
    "yres-organization": {
      "type": "http",
      "url": "https://api.yres.app/mcp/organization/<organisatie-uuid>",
      "headers": {
        "Authorization": "Bearer ${input:yres-mcp-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "yres-mcp-token",
      "type": "promptString",
      "description": "Yres Sanctum API token",
      "password": true
    }
  ]
}
```

Andere MCP-clients verbind je op dezelfde manier: een HTTP-server met het adres hierboven en de
`Authorization`-header met je token.

:::warning Behandel een token als een wachtwoord
Met een personal access token werkt een programma namens jou. Deel het niet en zet het nooit in
versiebeheer. Een token dat je niet meer gebruikt, trek je in op dezelfde pagina.
:::

## Rechten

- De assistent werkt met jouw rechten. Elke tool controleert je permissies zoals de webapp dat doet. Mag
  je geen pipelines starten of geen used tables aanpassen, dan kan de assistent dat ook niet. Wat de
  assistent in het datawarehouse doet, wordt onder jouw naam gelogd.
- Toegang met een personal access token staat standaard uit. Een beheerder zet de organisatieregel
  **Allow personal access tokens** aan voor de hele organisatie of voor afzonderlijke gebruikers. Staat de
  regel uit, dan meldt de assistent dat het verzoek door een organisatieregel is tegengehouden. Zie
  [Admin › Organization rules](https://yres.eu/nl/wiki/frontend/admin#organization-rules-vanaf-v157).
- De regel **SSO required** en de [firewall](https://yres.eu/nl/wiki/frontend/admin#firewall) van je organisatie gelden ook voor de
  MCP-server.
- Een token werkt alleen voor de MCP-server en de koppelingen die ervoor bedoeld zijn. De rest van de
  webapp gebruik je met je normale login.

## Goed om te weten

- Used tables, changes en projecten beheer je in de development-omgeving; andere omgevingen krijgen ze
  via een release. Opvragen, laden, metadata vernieuwen en de monitoring bekijken kan ook in een andere
  omgeving. Noem de assistent dan de gewenste omgeving. Zonder die opgave werkt hij in development.
- Elke tabelwijziging hoort bij een open change. Bij het toevoegen of aanpassen van een used table koppelt
  de assistent die aan een open change. Heeft de tabel al een change, dan gebruikt hij die.
- Organisaties met één omgeving werken met een vaste change. Daar zijn de tools voor changes en projecten
  niet beschikbaar.
- Sommige tools vragen een minimale versie van het datawarehouse. Een change naar een ander project
  verplaatsen kan vanaf DWH-versie 1.56. Draait de omgeving een oudere versie, dan meldt de assistent
  welke versie nodig is.
- Het toevoegen en aanpassen van used tables loopt als achtergrondproces, net als in de webapp. De
  assistent volgt het proces en controleert daarna het resultaat. Een load kan lang duren; vraag de
  assistent gerust later naar de status.
- Een token verloopt standaard na 30 dagen. Je kunt bij het aanmaken een eerdere datum kiezen. Daarna maak
  je een nieuw token aan.
- Per token verwerkt de server maximaal 300 verzoeken per minuut. Daarmee blijft de webapp bereikbaar als
  een assistent veel verzoeken achter elkaar doet.
