Een MCP Server koppelen aan een browseromgeving: configuratie en probleemoplossing

MCP (Model Context Protocol) laat een AI-assistent een browser bedienen zonder dat je elke interactie zelf hoeft te programmeren. De assistent kan de benodigde tools in de juiste volgorde aanroepen en de taak zelfstandig uitvoeren.

In de praktijk zit het probleem meestal niet in het protocol zelf, maar in wat je moet installeren, waarmee je verbinding maakt, hoe je referenties doorgeeft en hoe je controleert of de verbinding echt werkt. Door die vier punten stap voor stap af te lopen, komen de meeste problemen al tijdens de configuratie aan het licht.

Controleer eerst drie dingen

Ten eerste heb je een client voor de browserautomatiseringsomgeving nodig die een lokale interface aanbiedt, en de versie moet een lokale API ondersteunen. Bij een oudere versie kan die interface volledig ontbreken, terwijl je alleen merkt dat de toollijst leeg blijft. Ten tweede heb je Node.js 18 of hoger nodig. De meeste MCP Servers zijn in TypeScript gebouwd en hebben een Node-runtime nodig. Ten derde heb je een AI-tool nodig die MCP ondersteunt.

Zet de controle van de clientversie helemaal vooraan. Een aanzienlijk deel van verbindingsproblemen en lege toollijsten wordt eenvoudig veroorzaakt door een verouderde versie en heeft niets met de server te maken.

Waar maak je verbinding mee?

Wanneer de client start, wordt op de lokale machine een API-service gestart die luistert op een loopback-adres. De poort kun je zien en wijzigen in de interface-instellingen van de client. Is de poort bezet, kies dan een andere en start de client opnieuw.

De MCP Server benadert de omgeving via dit lokale adres; er loopt geen verkeer via het openbare internet. Het omgekeerde is net zo belangrijk: deze service hoort alleen lokaal beschikbaar te zijn en mag niet extern worden blootgesteld.

Hoe geef je referenties door?

Genereer in de clientinstellingen een API Key. Sommige implementaties gebruiken twee delen: een ID en een Key. Deze referenties geven in de praktijk controle over alle omgevingen onder je account; iemand die ze in handen krijgt, kan die omgevingen mogelijk starten, wijzigen of verwijderen.

Sla de basismaatregelen niet over. Zet referenties nooit in een code-repository. Gebruik omgevingsvariabelen of een lokaal configuratiebestand en voeg dat bestand toe aan de ignore-lijst. Roteer de referenties direct wanneer de teamsamenstelling verandert. Als je per doel aparte referenties kunt genereren, doe dat dan; incidenten zijn zo gemakkelijker te herleiden en een afzonderlijke referentie kan apart worden ingetrokken. Geef in de configuratie van de AI-tool zowel het endpoint als de referenties via omgevingsvariabelen door en zet ze niet hardcoded op de commandoregel, waar ze sporen kunnen achterlaten.

Registreer de service

Registreren betekent doorgaans dat je een servicedefinitie toevoegt aan het configuratiebestand van de AI-tool. Die bestaat uit drie delen: de startmethode, dus een commando of pad naar het entry-bestand; omgevingsvariabelen met het lokale endpoint en de referenties; en een service-ID, oftewel de naam die in de toollijst verschijnt.

Start de AI-tool opnieuw nadat je de service hebt geregistreerd. De meeste tools lezen de configuratie maar één keer bij het starten. Een wijziging zonder herstart werkt daarom praktisch alsof er niets is veranderd.

Controleren of de verbinding echt werkt

Doe dit in twee stappen en houd de volgorde aan.

Bekijk eerst de toollijst. Daar zouden browsergerelateerde tools moeten verschijnen; daarmee bevestig je dat de service is herkend. Geef daarna een alleen-lezen taak, bijvoorbeeld het tonen van alle huidige omgevingen. Een alleen-lezen actie heeft geen bijwerkingen, maar controleert authenticatie, netwerk en service in één keer. Als deze stap niet slaagt, heeft het nog geen zin om latere taken te proberen.

Wat kun je doen nadat de verbinding werkt?

Als de service werkt, kan een AI-assistent doorgaans omgevingen opvragen en doorzoeken, omgevingen aanmaken en basisparameters instellen, omgevingen starten en stoppen, een netwerkuitgang aan een omgeving koppelen en op een pagina navigeren, klikken, velden invullen en screenshots maken.

Je gebruikt dit in natuurlijke taal: beschrijf het doel en de assistent bepaalt welke tools in welke volgorde worden aangeroepen. Eén onderscheid wordt gemakkelijk door elkaar gehaald: de AI bepaalt wat er gebeurt, terwijl de omgevingslaag bepaalt onder welke identiteit het gebeurt. Door die verantwoordelijkheden apart te houden, kun je bij problemen sneller bepalen in welke laag je moet zoeken.

Volgorde voor probleemoplossing als er geen verbinding is

Is de toollijst leeg, controleer dan eerst of het pad naar het configuratiebestand klopt, daarna of de AI-tool echt opnieuw is gestart en probeer vervolgens de service handmatig te starten om te zien of die zelfstandig kan opkomen. Als een van deze drie stappen mislukt, is er nog geen reden om het protocol te verdenken.

Authenticatiefouten hebben meestal maar twee oorzaken: de Key is met een extra teken of regeleinde gekopieerd, of de omgevingsvariabele is niet goed ingelezen. De Key opnieuw kopiëren is vaak sneller dan de configuratie steeds opnieuw aanpassen.

Verbindingstime-outs wijzen meestal naar de lokale kant. Controleer of de client draait en of de poort bezet of door een firewall geblokkeerd is. De meeste MCP Servers vereisen dat de client actief blijft; zodra de client wordt gesloten, kunnen de tools niet meer worden aangeroepen.

Werkt de verbinding wel maar worden acties verkeerd uitgevoerd, dan is timing vaak de oorzaak. Geef in de instructie duidelijk aan op welke toestand moet worden gewacht voordat de volgende stap begint, in plaats van de assistent te laten raden of de pagina al volledig is geladen.

Een ander probleem dat vooraf gemakkelijk wordt gemist, is dat meerdere taken dezelfde omgeving delen. Sessies, Cookies en cache overschrijven elkaar, taken gaan elkaar beïnvloeden en uiteindelijk lijkt het op willekeurige uitval in plaats van een duidelijke fout. Een stabielere aanpak is om elke taak een eigen omgeving te geven en de omgevingslaag bulkcreatie en opruimen te laten verzorgen. De omgevingsisolatie en het centrale beheer van PurpleMark zitten precies in deze laag; nadat MCP is gekoppeld, blijven taakorkestratie en identiteitsbeheer twee aparte zaken.

Twee extra valkuilen

Wanneer een automatiseringsframework de browser overneemt, moet de driverversie overeenkomen met de engineversie die de client gebruikt. De client geeft meestal een bruikbaar driverpad terug, maar de versies kunnen alsnog niet bij elkaar passen. Automatisch synchroniseren met een versiebeheertool is vaak eenvoudiger, terwijl het pagina-endpoint nog steeds de door de client teruggegeven waarde kan gebruiken; die twee zaken botsen niet.

Concurrentie is het tweede punt. Eén browserproces gebruikt ongeveer 300 tot 500MB geheugen. Het is daarom aan te raden op één machine niet meer dan 5 omgevingen tegelijk te starten. Daarboven kunnen starts mislukken en processen zelfs crashen. Gebruik voor pagina-acties ook geen vaste wachttijden: zet de time-out voor het laden van een pagina op 30 seconden en gebruik expliciete waits voor elementen, maximaal 20 seconden. Dat is betrouwbaarder dan sleep.

Eén belangrijke grens

MCP lost het technische probleem op van hoe AI een browser bedient; het verandert de regels van een platform niet. De taak zelf moet nog steeds voldoen aan de servicevoorwaarden van het doelplatform. Wat technisch mogelijk is en wat volgens de regels is toegestaan, zijn twee afzonderlijke beoordelingen.

Gebruik de officiële documentatie voor details over protocol en interfaces en controleer vóór je begint of de geplande taak op het doelplatform is toegestaan.