Notion MCP Server: Tools, Setup en Veilig Scopen

Wat de Notion MCP server is

De Notion MCP server is een remote Model Context Protocol server voor Notion. MCP is de open standaard waarmee een agent tools op een extern systeem kan ontdekken en aanroepen; de implementatie van Notion stelt het doorzoeken van werkruimtes, het lezen en schrijven van pagina's en databases, en opmerkingen beschikbaar als aanroepbare tools.

De documentatie van TrueFoundry beschrijft de functionaliteit als het zoeken, ophalen, aanmaken en bijwerken van pagina's, databases en opmerkingen, met tools die de notion-*-conventie volgen — notion-search, notion-fetch, notion-create-pages, notion-update-page. Gegroepeerd op functionaliteit:

Dat Resources-tabblad is belangrijk: de meeste MCP servers stellen alleen tools beschikbaar, dus Resources is een tweede ophaalpad dat eenvoudig over het hoofd wordt gezien bij het controleren van wat een agent kan bereiken.

Omdat het een remote server is, hoeft er geen container te draaien en is er geen npx-proces per laptop nodig — je verwijst een client naar een URL en authenticeert, het patroon dat nu de standaard is voor remote MCP servers.

Wat agents er daadwerkelijk mee doen

De waardevolle toepassingen combineren meerdere tools en leunen sterk op zoekfunctionaliteit omdat Notion-inhoud van nature ongestructureerd is:

• Vragen beantwoorden vanuit de wiki. Voer notion-search uit op een vraag, haal de drie meest relevante pagina's op en geef antwoord met bronvermeldingen naar de pagina-URL's.
• Samenvatting van vergadernotities. Zoek notitiepagina's van de afgelopen twee weken, haal ze op inclusief discussies, extraheer actiepunten en maak één samenvattende pagina aan met toegewezen eigenaren.
• Specificaties opstellen. Haal een productbrief op, verzamel de gekoppelde onderzoekitems uit de database, stel een specificatie op als nieuwe pagina en plaats een opmerking op de brief met een link.
• Projectonderhoud. Doorzoek een projectendatabase naar verouderde statusvelden, haal elke projectpagina op en plaats een opmerking waarin de eigenaar om een update wordt gevraagd.

Het onderscheid tussen lezen en schrijven is hier scherper dan bij de meeste tools. Lezen is het hoofddoel — ophalen van informatie is waarom je het verbindt. Schrijven is handig, maar zelden essentieel, en het is het gedeelte dat een pagina kan overschrijven waar een mens een week aan heeft gewerkt. Handig is dat de tools van Notion al zijn gelabeld als Read-only of Destructive, zodat het tabblad Tools direct laat zien wat wat is zonder verdere inspectie.

Waarom rechtstreeks verbinden op teamschaal misgaat

Het risicoprofiel van Notion verschilt van dat van een code-host. Het gevaarlijke scenario is niet dat een agent kwaadwillig een pagina overschrijft — het is dat een agent legitiem veel meer leest dan ooit de bedoeling was.

Overerving van rechten maakt de scope onzichtbaar. Toegang in Notion is gestructureerd als een paginaboom: verleen toegang tot een bovenliggende pagina en de rechten stromen door naar elke onderliggende pagina, subpagina en database eronder. Wanneer iemand "de Engineering wiki" deelt met een integratie, stellen ze zich de landingspagina voor. Wat ze daadwerkelijk hebben gedeeld, is alles wat zich in drie jaar tijd onder die node heeft opgehoopt — inclusief de salarisplanningspagina die een manager daar snel tussen heeft geplaatst. Niemand is van plan een agent HR-gegevens te geven. Overerving regelt dat automatisch.

Toestemming op werkruimteniveau is te globaal. Het OAuth-scherm van Notion vraagt om een werkruimte te kiezen en toont vervolgens de verleende categorieën — toegang tot pagina's en databases, zoeken, werkruimtegebruikers. Het vraagt nooit om specifieke pagina's te selecteren. De eenheid van toestemming is veel groter dan de eenheid van behoefte, dus de feitelijke standaard is "de agent kan erg veel zien" tenzij iets dit beperkt.

Zoekfunctionaliteit versterkt dit. Een te ruime autorisatie zou nog beheersbaar zijn als een agent pagina-URL's moest raden. Dat hoeft niet. notion-search is een hulpmiddel voor ontdekking: richt een agent op een werkruimte en hij zal de gevoelige pagina's vinden, want dat is zijn taak. Ophaalkwaliteit en de potentiële impact schalen hand in hand.

Niemand kan reconstrueren wat er is gelezen. Notion logt API-activiteit. Het logt niet dat jouw interne support-agent zocht naar "ontslagvergoeding" tijdens het beantwoorden van een vraag uit een Slack-thread. Leesacties vormen het risico-oppervlak, en leesacties worden achteraf het minst snel opgemerkt.

Dit is geen reden om de Notion MCP server over te slaan. Het is een reden om er een control plane voor te plaatsen — precies waarvoor een MCP gateway is bedoeld.

Wil je de bewaakte, gescopete versie zien?

Start een TrueFoundry-account, verbind Notion met OAuth per gebruiker en geef je team in één sessie een read-only werkruimte-agent.

Gratis aan de slag

De Notion MCP server verbinden via TrueFoundry

Op TrueFoundry is Notion een TrueFoundry Managed MCP. TrueFoundry publiceert door het platform geverifieerde serverdefinities naar een beheerde catalogus; om er een in te stellen hoef je alleen een Name op te geven. Het platform beheert elke URL, auth-details, scopes en credentials — en houdt deze actueel wanneer de upstream provider ze wijzigt.

Stap 1 — Open de catalogus. Ga naar MCP Servers in de zijbalk, klik op Add new MCP Server en selecteer Connect TrueFoundry Managed MCPs. Zoek notion — gecatalogiseerd als "Notion is a collaboration and productivity tool" — en klik op + Add. TrueFoundry registreert de server en opent de detailpagina.

TrueFoundry managed MCP-catalogus met de notion-kaart uitgelicht tussen de beschikbare, door het platform geverifieerde MCP servers

Dat is de gehele registratie — geen URL om te plakken, geen Notion-integratie aan te maken, geen client secret om op te slaan.

Stap 2 — Start de verbinding. Het tabblad Tools opent met "You’re not connected to this MCP Server." Klik op Connect Now om de OAuth2-autorisatie te starten; de detailpagina toont het authenticatietype voordat je ergens op klikt.

Stap 3 — Goedkeuren bij de gateway. Een "Connect via TrueFoundry AI Gateway" pop-up toont de MCP Gateway URL, de redirect URL en de te autoriseren servers. Controleer dit en klik op Approve. Je wordt vervolgens achtereenvolgens naar elke MCP server omgeleid — handig om te weten als je er meerdere tegelijk autoriseert, omdat de flow een keten is in plaats van één enkele stap.

Stap 4 — Autoriseer je Notion-werkruimte. Het toestemmingsscherm van Notion opent. Selecteer de werkruimte, controleer de toegang die wordt verleend — pagina- en databasetoegang, zoeken, werkruimtegebruikers — bevestig dat je de redirect URL vertrouwt en klik op Continue.

Lees dit scherm aandachtig — dit is het moment waarop het overervingsprobleem een bewuste keuze wordt. Degene die op Continue klikt, bepaalt hoeveel van de werkruimte een agent kan doorzoeken.

Stap 5 — Controleer de tools. Het tabblad Tools wordt gevuld met de tools van Notion, elk voorzien van een beschrijving, een Try-knop en een Read-only of Destructive label. Resources verschijnen op een eigen tabblad.

Hoe authenticatie daadwerkelijk werkt

TrueFoundry scheidt inkomende authenticatie (hoe een client zich bewijst tegenover de gateway) van uitgaande authenticatie (hoe de gateway zich bewijst tegenover Notion). De lagen zijn onafhankelijk van elkaar, en dat onderscheid maakt scoping per gebruiker mogelijk.

Inkomend — vier ondersteunde methoden:

Één kanttekening is voor Notion belangrijker dan voor vrijwel elke andere server: Virtual Account tokens geven elke aanvraag identieke toegang. Dat is onbruikbaar voor scoping per gebruiker — een gedeeld token betekent dat elke agent dezelfde gecombineerde verzameling pagina's ziet, wat precies het scenario is dat je wilt vermijden. Gebruik inkomend een PAT of een IdP-token zodat de identiteit behouden blijft tot aan de uitgaande stap.

Uitgaand — Notion gebruikt OAuth2. Elke gebruiker autoriseert zijn eigen werkruimte, en TrueFoundry beheert de toestemming, tokenopslag en verversing, waarbij bij elke tool-call het juiste token per gebruiker wordt ingevoegd. Autorisatie vindt rechtstreeks plaats tussen het account van de gebruiker en zijn Notion-werkruimte; TrueFoundry ontvangt geen Notion-credentials. Voor managed MCP's is de redirect URI altijd https://auth.truefoundry.com/mcp/oauth2/callback.

Het praktische effect vormt de kern van dit artikel. Een agent die handelt namens een support engineer zoekt in de pagina's die die engineer kan zien; een agent die handelt namens iemand van HR zoekt in HR-pagina's. Geen enkel gedeeld token bevat de gecombineerde toegang van iedereen, en wanneer iemands Notion-toegang wijzigt, verandert het bereik van diens agent automatisch mee — zonder dat iemand een configuratie hoeft aan te passen. ## Tools scopen voor uitrol

OAuth per gebruiker beperkt welke pagina's toegankelijk zijn; toolbeheer beperkt wat ermee gedaan kan worden. Gebruik beide.

Schakelaars per tool. Schakel een tool uit en deze wordt volledig weggelaten uit tools/list — clients zien deze nooit en de tool kan niet worden aangeroepen. Dit is geen filtering op prompt-niveau; de tool is simpelweg niet beschikbaar. Voor een Notion-kennisagent laat de gebruikelijke configuratie zoeken en ophalen ingeschakeld en schakelt alle schrijftools uit. Een agent zonder notion-update-page kan niet worden overgehaald om een pagina te overschrijven, ongeacht wat een schadelijke paginainhoud beweert.

Enable new tools by default. Aan: tools die Notion later uitbrengt verschijnen automatisch. Uit: alleen tools die je expliciet hebt ingeschakeld zijn beschikbaar en nieuwe blijven verborgen totdat je ze goedkeurt. Voor een server die toegang heeft tot je gehele interne wiki is uit de juiste standaardinstelling — uitbreiding van functionaliteit moet een bewuste keuze zijn.

Bulk Action. Verandert elke rij in selectievakjes met Select all — de snelle route naar een read-only Notion-server: selecteer alles, vink zoeken en ophalen uit, en sla op.

Klik op het potlood bij een tool om Edit Tool te openen. De overschrijving van de Description (tot 20.000 tekens) stuurt de tool-selectie — handig om een model te laten weten welk ophaalpad de voorkeur heeft, aangezien Notion zowel zoeken als Resources biedt. MCP Tool Annotations stellen readOnlyHint of destructiveHint in voor clients die deze ondersteunen. De tools van Notion worden reeds geannoteerd geleverd, dus je bevestigt ze in plaats van ze zelf te schrijven — maar controleer ze toch, omdat het onderstaande goedkeuringsbeleid precies op die annotaties is gebaseerd.

Wie wat kan doen: rollen voor medewerkers

Toegangsbeheer is gekoppeld aan gebruikers, teams of virtuele accounts op twee dimensies: welke MCP servers een identiteit kan bereiken, en welke tools binnen een server aangeroepen kunnen worden. Voeg medewerkers toe via de instellingen van de server en wijs een rol toe:

Voor Notion is het nuttige onderscheid dat degene die beslist wat een agent met de wiki mag doen, meestal niet degene is die de inhoud bezit: een platformteam heeft het beheer (Manager), functionele teams zijn gebruiker (User), en een eigenaar van kennisbeheer of compliance heeft goedkeuringsrechten (Approver). Dit is hetzelfde MCP toegangsniveau-model als voor elke andere server in je register.

Klaar om je eerste server te scopen?

Verbind Notion, schakel de schrijftools uit en geef elke gebruiker een agent die begrensd is door hun eigen paginatoegang.

Start gratis op TrueFoundry

Menselijke goedkeuring voor destructieve tools

Het uitschakelen van schrijfrechten is een grove maatregel. Soms wil je wel dat een agent een specificatiepagina aanmaakt of een projectdatabase bijwerkt — alleen niet onbeheerd. Wanneer een bewaakte tool wordt aangeroepen via de gateway, wordt de aanroep ingehouden in plaats van uitgevoerd, wordt er een verzoek aangemaakt en worden goedkeurders op de hoogte gesteld. Zodra de aanroep is goedgekeurd, slaagt dezelfde aanroep van dezelfde aanvrager totdat de toestemming verloopt.

Maak een beleid aan onder AI Gateway → Policies → MCP Tool Approval (gemarkeerd als Beta in de console). Elk beleid vermeldt de servers die het bewaakt en kiest een approval scope:

Omdat de tools van Notion vooraf geannoteerd zijn, is approval_scope: destructive hier bijzonder effectief — het bewaakt de gehele klasse van schrijfacties zonder afzonderlijke toolnamen op te noemen, en blijft werken wanneer Notion een nieuwe schrijftool toevoegt. Wanneer scopes overlappen, wint de meest specifieke: named > destructive > all.

De Geldigheid is Once (één enkele uitvoering) of op tijdsbasis (een duur in minuten). Bij een conflict tussen beleidsregels wint de meest beperkende — Once is strikter dan een venster van 10 minuten, wat weer strikter is dan 30 minuten. Goedkeurders ontvangen meldingen via e-mail, Slack, PagerDuty of MS Teams en beoordelen verzoeken in de console:

Elk verzoek toont de tool, het beleid, de aanvrager en de daadwerkelijke argumenten — zodat een goedkeurder ziet welke pagina een agent wil bijwerken voordat deze wordt goedgekeurd. Zolang het verzoek in behandeling is, ontvangt de aanroeper een JSON-RPC-resultaat met _meta.approval_status: "pending" in plaats van een foutmelding, zodat een correct geconfigureerde agent wacht en het opnieuw probeert. Toestemmingen gelden per aanvrager, en een weigering blokkeert iemand niet permanent — de volgende aanroep genereert een nieuw verzoek. Om de toegang duurzaam te blokkeren, schakel je de tool uit of verwijder je de gebruiker.

Testen in de Tool Playground

Test tools eerst handmatig. Klik op Try naast een tool op de detailpagina van de server. Voer voor notion-fetch de pagina- of databron-Id (of URL) in, schakel optioneel Include transcript of Include discussions in, klik op Execute Tool en lees de JSON in het rechterpaneel. Try is uitgeschakeld voor tools die je hebt uitgeschakeld.

Bij Notion dient de playground ook als de snelste en meest betrouwbare controle van je scope. Voer notion-search uit op een term die vertrouwelijk zou moeten zijn — zoals een salarisschaal of een niet-aangekondigde codenaam — en bekijk wat er binnen jouw autorisatie wordt geretourneerd. Als er onverwachte resultaten verschijnen, is je overervingsstructuur breder dan gedacht. Het is veel beter om daar hier achter te komen dan via een transcript van een agent.

Gebruik vanuit je IDE

TrueFoundry stelt de server beschikbaar via een HTTP-transportlaag. Open het tabblad How To Use voor de tenant-specifieke Gateway URL en kant-en-klare codefragmenten.

Het ondersteunt Cursor, VS Code, Claude Code, Claude Web, Claude Desktop, Windsurf, Codex en de Python en TypeScript MCP SDK's. Show API Key toont de sleutel als je client deze als header vereist. Kopieer de URL van dit tabblad in plaats van deze handmatig samen te stellen — de URL is tenant-specifiek, en een handmatig gebouwd eindpunt is de meest voorkomende oorzaak van een client die wel verbindt maar geen tools toont.

Wat het oplevert zodra het achter de gateway staat

Metrieken per tool. Het tabblad Tool Metrics toont het aantal aanroepen, de latentieverdeling en de foutpercentages per tool — zo ontdek je of een agent notion-search veertig keer per gesprek aanroept, of dat notion-fetch fouten geeft op je grootste databases.

Volledige verzoek-observeerbaarheid. Elke aanroep wordt getraceerd met de aanroepende gebruiker, toolnaam, invoergegevens en latentie, en kan via OpenTelemetry worden geëxporteerd naar Grafana, Datadog of Prometheus. Op een server waar voornamelijk gelezen wordt, is dit cruciaal — het is de enige manier om de vraag te beantwoorden: "wat heeft de agent gelezen, en voor wie?"

Veiligheidsregels (Guardrails). Hooks worden uitgevoerd bij mcp_pre_tool (voorafgaand aan de aanroep) en mcp_post_tool (nadat het resultaat terugkeert), waarmee inhoudsbeleid wordt afgedwongen op verzoek en antwoord. Op een wiki-server bewijst de post-tool hook zijn waarde — deze onderschept inloggegevens of een salariscijfer in een geretourneerde pagina voordat deze het model bereikt.

Lage overhead. De gateway voegt slechts ongeveer 3–4 ms latentie toe en verwerkt 350+ RPS op een enkele vCPU, waardoor het in het actieve verwerkingspad staat zonder een knelpunt te worden.

Één centraal register. Zodra er meerdere servers zijn geregistreerd, bundelt een Virtual MCP Server een geselecteerde reeks tools van verschillende servers achter één eindpunt — zo krijgt een onderzoeksagent toegang tot Notion-zoeken én Slack-historie, maar niets dat schrijfopdrachten kan uitvoeren.

Toegang intrekken

Tenant-beheerders kunnen alle opgeslagen inloggegevens wissen via het menu met de drie puntjes naast Edit. Revoke all tokens verwijdert alle auth-overschrijvingen en opgeslagen OAuth-tokens voor alle gebruikers en virtuele accounts op die server. Dit wordt van kracht bij het eerstvolgende verzoek en wordt vastgelegd in de Activity Logs. Dit is onomkeerbaar — iedereen moet daarna de OAuth-toestemming opnieuw doorlopen.

Één beperking is belangrijk: dit verwijdert alleen tokens uit de gateway. Het trekt de autorisatie binnen Notion zelf niet in. Trek bij een echt incident de verbinding dus ook in via de werkruimte-instellingen van Notion. Alleen tenant-beheerders kunnen deze actie uitvoeren — MCP Server Managers zien deze optie niet.

Belangrijke aandachtspunten

Overerving bepaalt alles. Controleer voordat je verbindt de hoofdpagina's waar het autoriserende account toegang toe heeft en vraag je af wat zich eronder heeft verzameld. De verleende toegang betreft niet alleen de pagina die je voor ogen hebt, maar de gehele onderliggende structuur.

Resources vormen een tweede ingang. Notion stelt MCP Resources beschikbaar op een afzonderlijk tabblad, dus een controle die alleen het tabblad Tools omvat is onvolledig. Controleer beide.

Gebruik geen gedeeld token voor een gedeelde wiki. Eenmalig verbinden met een service-identiteit kost minder insteltijd — maar het wist alle grenzen per gebruiker uit en vervangt ze door de gecombineerde toegang van alles wat die identiteit kan zien. OAuth per gebruiker vereist meer handelingen, maar is absoluut de betere keuze.

Gerelateerde artikelen

• What Is an MCP Gateway: Architecture and Use Cases — de architectonische basis achter dit artikel
• MCP Access Control: Securing AI Agents with an MCP Gateway — hoe rechten op tool- en serverniveau werken
• MCP Authenticatie Uitgelegd — het inbound en outbound auth-model
• Virtuele MCP Server Uitgelegd — het bundelen van meerdere servers in één eindpunt
• MCP Server Security Best Practices — de bredere hardening checklist

Conclusie

Notion is het meest nuttige dat je aan een agent kunt geven en het moeilijkst te begrenzen, om dezelfde reden: het is waar alles terechtkomt. Het risico is niet dat een agent een pagina herschrijft — het zijn de overgeërfde paginaboom-permissies die een zoektool stilzwijgend een groter corpus overhandigen dan waar iemand toestemming voor heeft gegeven, en zoeken is erg goed in het vinden van de interessante delen van een groot corpus.

OAuth per gebruiker lost dat op: het maakt het bereik van de agent een functie van de persoon voor wie hij handelt, niet een configuratie die iemand ooit heeft ingesteld. Het draaien van Notion als een beheerde MCP op TrueFoundry voegt de rest toe — toggles per tool in plaats van alles-of-niets-toegang, goedkeuringspoorten voor de writes, guardrails op request en response, en een getraced logboek van elke read.

Verbind de Notion MCP server op TrueFoundry

gratis te starten