Un aperçu du serveur MCP hébergé par Notion

Lorsqu’Anthropic a annoncé le Model Context Protocol (MCP) en novembre 2024, sa vision était simple, mais puissante : offrir aux entreprises technologiques et équipes de développement un langage universel pour découvrir des outils et interagir avec eux.

Le MCP dépasse les conventions telles que REST, qui alimentent les API Web depuis des décennies. Il fournit un contexte aux grands modèles de langage (LLM) pour leur dire quand et comment utiliser chacun des outils diffusés par un fournisseur tel que Notion, Figma ou Stripe. Le processus traditionnel consiste à assembler des documents techniques pour créer une intégration API classique. En évitant cette étape, la clientèle interagit avec les systèmes grâce à un langage naturel utilisé lors d’une conversation ou pour un flux de travail.

Cursor et Claude Code sont des clients MCP, ou des applications front-end pour LLM, qui agissent en tant qu’agents en contact avec l’utilisatrice ou l’utilisateur final. Ils convertissent les demandes exprimées en langage naturel en appels à actions (« outils ») proposés par différents prestataires de services, appelés serveurs MCP, comme Notion, Stripe ou Figma.

Au début de l’année, Notion a commencé à recevoir des demandes pour intégrer un serveur MCP à ses espaces de travail. Nous avions entendu parler de grandes entreprises qui avaient adopté des flux de travail axés sur l’IA, les intégrant à leurs processus de travail sur les connaissances et de développement de produits. Nous avions également entendu parler de créatrices et créateurs d’outils, de développeuses et développeurs, ainsi que d’ambassadrices et ambassadeurs Notion qui souhaitaient une solution simple pour migrer leurs données vers Notion, mais aussi pour interagir avec leurs espaces de travail à partir d’outils LLM connus tels que Cursor et Claude Desktop.

Dans un premier temps, nous voulions fournir les capacités d’API existantes de Notion sous forme d’actions pouvant être appelées par l’IA, afin de démontrer comment le modèle « outils » débride la productivité dans les flux de travail agentiques.

Nous avons commencé par publier une version téléchargeable du serveur-mcp-notion début avril. Il pouvait être installé dans Cursor ou Claude Desktop, mais avec les connaissances techniques requises. La configuration a nécessité la création d’une nouvelle intégration de l’API Notion, ainsi que la copie de la clé API dans les en-têtes MCP ou la création d’une image Docker. Une fois le serveur configuré, des flux ont pu être mis en place, tels que la création de pages dans Notion à partir des discussions avec l’agent d’IA.

En coulisses, la bibliothèque a analysé les spécifications OpenAPI publiques de Notion, une description formelle des points d’accès API disponibles et de leurs interfaces. Le serveur traitait ce fichier, convertissant les appels de l’outil MCP en appels API HTTP vers l’API publique de Notion à l’aide de la clé API que vous aviez configurée. Chaque point d’accès API était cartographié, puis associé à un outil MCP sur le serveur. Le serveur MCP recevait les demandes du client MCP et les traduisait en appels API, adaptés à votre téléchargement.

Même si l’adoption a été difficile et les fonctionnalités limitées, nous voulions agir rapidement afin de proposer quelque chose à notre communauté. Les commentaires des premiers utilisateurs et utilisatrices ont révélé deux points essentiels : la barrière technique était trop haute pour permettre une adoption à grande échelle et la cartographie API de chaque point d’accès API créait des expériences sous-optimales pour les agents d’IA, comme une consommation élevée de jetons contextuels due au travail avec des données hiérarchiques en blocs JSON.

Ces enseignements ont façonné notre itération suivante : nous avons travaillé dur pour mettre au point une combinaison puissante d’outils existants et nouveaux utilisables par tout le monde, renforçant ainsi la valeur de Notion en tant qu’espace de travail connecté. Imaginez passer d’un document de spécifications dans Notion à un prototype fonctionnel dans Cursor, mettre à jour le statut des tâches à la volée et informer les parties prenantes du projet, le tout sans quitter votre éditeur de code.

L’idée principale est de faciliter la connexion à votre espace de travail Notion pour les outils d’agent d’IA, offrant ainsi une expérience plus intuitive pour les agents avec les avantages suivants :

• Hébergement de notre serveur MCP avec un cycle de développement rapide utilisant notre base de code existante et nos outils internes : Notion peut rapidement mettre à jour ses fonctionnalités sans que vous ayez besoin de télécharger de nouveaux packages.

• Création d’une intégration centrale unique qui expose une suite d’outils sur mesure optimisés pour les agents d’IA, et non des appels HTTP vers l’API : nous pouvons ignorer les pratiques RESTful API Web et livrer des fonctionnalités « privées » accompagnées de descriptions adaptées aux LLM, accessibles uniquement via le serveur MCP, pour une expérience agentique optimale.

Désormais, vous passez par un processus d’autorisation OAuth en un clic pour vous connecter en toute sécurité à la même intégration publique. Vous l’installez sur votre espace de travail et choisissez les pages ou bases de données à partager.

Une fois la connexion établie, le flux vous redirige vers l’outil utilisé (comme Cursor). Notre serveur MCP gère les sessions et stocke en toute sécurité le jeton API provenant de l’échange OAuth, afin d’authentifier l’API publique de Notion lorsque des appels d’outils sont effectués.

Nous avons travaillé étroitement avec l’équipe d’ingénierie de Cursor afin de privilégier une expérience de connexion OAuth agréable grâce à l’utilisation du protocole HTTP diffusable. Nous prenons également en charge les SSE (événements envoyés par le serveur) pour assurer la compatibilité avec davantage de clients, car il s’agit de l’autre protocole de transport majeur recommandé pour les MCP.

Outre la suite technologique et l’hébergement, nous devions également sélectionner les outils d’IA à proposer. Notre approche consistait à travailler avec l’équipe chargée de développer l’agent Notion, intégré à l’application, afin d’exposer les outils axés sur l’IA de préférence via les points d’accès API /v1/ existants.

Pour créer l’ensemble d’outils du MCP, nous avons combiné deux types d’opérations en arrière-plan :

• Outils Notion orientés agents. par exemple, créer-pages et mettre à jour-page sont des réécritures complètes des API « Créer et Mettre à jour des page existantes », fournissant des interfaces plus adaptées à une conversation avec un agent d’IA qu’une API Web traditionnelle rigide.

  • Conçus avec Markdown façon Notion, avec des descriptions d’outils et des réponses adaptées aux flux de travail agentiques, plutôt qu’à un fichier JSON déterministe et structuré pour les intégrations backend.

  • Markdown offre une densité de contenu efficace par jeton LLM, ce qui nécessite moins d’interactions avec les outils et réduit les coûts par rapport au serveur MCP open source pour les cas d’utilisation courants.

  • L’outil de recherche est également adapté à cette réalité. Nous avons exposé l’API de recherche v1 existante pour couvrir les cas d’utilisation simples ou les comptes où l’IA de Notion n’est pas activée, mais l’outil de recherche principal prend en charge la recherche sémantique via des questions, faisant apparaître des pages dans votre espace de travail Notion ainsi que plus de dix applications tierces connectées !

• Outils API existants : en nous inspirant du succès du serveur MCP open source, nous avons comblé les lacunes fonctionnelles en ajoutant des outils MCP qui intègrent les API v1 existantes.

  • Par exemple, la fonctionnalité API v1 de l’outil créer-commentaire a été enrichie de descriptions d’outils adaptées à l’IA afin d’éviter les imperfections du package open source.

  • Ces instructions fournissent à votre client MCP des informations contextuelles sur quand et comment utiliser chaque outil.

Cette stratégie combinée offre des fonctionnalités étendues tout en garantissant que les détails, tels que les URL et les identifiants de Notion, fonctionnent parfaitement pour les appels d’outils dans votre fenêtre de discussion.

La version bêta du serveur MCP de Notion nous a permis de tester une nouvelle façon de représenter le contenu des pages, beaucoup plus facile à créer, modifier et consulter pour les agents d’IA. Nous avons été la première entreprise à proposer des spécifications Markdown améliorées « façon Notion », créant ainsi un langage de balisage puissant adapté à la vaste gamme de blocs de Notion.

Si vous nous suivez depuis un certain temps, vous vous souvenez peut-être de notre article de blog de 2022 sur la création de l’API Notion. À l’époque, nous avions préféré JSON à Markdown afin d’offrir une plus grande expressivité, comme les couleurs de texte enrichi, les bases de données et d’autres fonctionnalités d’édition spécifiques à Notion que CommonMark Markdown ne peut pas modéliser.

Trois ans plus tard, nous avons entendu vos difficultés pour effectuer plusieurs requêtes API afin de travailler avec des sous‑blocs dans un format JSON hiérarchique. Nous sommes revenus à Markdown pour introduire la parité des fonctionnalités avec les blocs Notion, en testant cette approche exclusivement sur notre serveur MCP distant.

Voici un aperçu des spécifications Markdown façon Notion :

Encadrés

Colonnes

Pages

Bases de données

Vous trouverez plus de détails dans les descriptions des outils disponibles via le serveur MCP. En fait, vous pouvez discuter avec votre agent d’IA et lui demander de vous résumer les spécifications Markdown façon Notion ! Sinon, laissez-nous nous occuper des détails techniques et décrivez en langage naturel ce que vous souhaitez ajouter ou modifier dans une page. Laissez le LLM faire le reste.

Ce lancement n’est que le début de notre aventure pour faire de Notion la plateforme ultime du travail intellectuel basé sur l’IA. Alors que nous poursuivons le développement de nos capacités MCP, nous nous concentrons toujours sur ce qui compte le plus : rendre des outils puissants accessibles à tout le monde, sans expertise technique.

Nous continuons également à collaborer avec Cursor et d’autres équipes afin d’ouvrir la voie vers de nouvelles conventions qui rendront le MCP plus facile à découvrir, plus sûr et plus fiable, comme des marketplaces de serveurs et de clients MCP de confiance et des protocoles de découverte de serveurs.

Nous avons hâte de découvrir ce que vous allez créer avec le serveur MCP de Notion ! Partagez vos créations avec nous sur les réseaux sociaux en mentionnant @NotionHQ.