Ga naar hoofdinhoud

AI-assistent (MCP)

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.

OnderwerpWat de assistent kan doenTools
OmgevingenDe omgevingen van je organisatie opvragen (dev, test, prod).list-environments-tool
BronnenJe databronnen opvragen, met details zoals de installatiestatus en welke optionele tabelinstellingen de bron ondersteunt.list-data-sources-tool, get-data-source-tool
BronnenDe tags van een bron bijwerken.update-data-source-tags-tool
Tabellen bekijkenDe used tables van een bron opvragen, en van één tabel de volledige laadconfiguratie.list-used-tables-tool, get-used-table-tool
Tabellen kiezenBekijken 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 toevoegenEen brontabel als used table toevoegen, of een endpoint van een REST-bron.create-used-table-tool, create-used-rest-service-table-tool
Tabellen aanpassenDe laadconfiguratie van een bestaande used table wijzigen, zoals het laadtype, de kolommen of de sleutel.update-used-table-tool
ChangesChanges 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
ProjectenProjecten opvragen, aanmaken, bijwerken of verwijderen zolang ze open staan.list-projects-tool, create-project-tool, update-project-tool, delete-project-tool
LadenEen bron laten laden: één tabel of alle used tables van de bron.load-data-source-data-tool
MetadataDe metadata van een bron opnieuw laten inlezen, zodat nieuwe tabellen en kolommen zichtbaar worden.refresh-data-source-metadata-tool
Voortgang volgenDe status van een gestarte pipeline-run of van een achtergrondproces volgen.get-pipeline-run-tool, get-monitor-tool
MonitoringDe 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.
  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.

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:

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:

{
"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:

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:

{
"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.

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.
  • De regel SSO required en de 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.