Notions gehosteter MCP-Server: ein Blick ins Innere

Als Anthropic im November 2024 das Model Context Protocol (MCP) angekündigt hat, war die Vision einfach, aber kraftvoll: Technologieunternehmen und Entwickler/-innen sollten sich auf eine universelle Sprache einigen, um Tools zu entdecken und mit ihnen zu interagieren.

MCP übersteigt Standards wie REST, das seit Jahrzehnten für Web-APIs verwendet wird. Es stellt großen Sprachmodellen (LLMs) Kontext zur Verfügung, sodass sie wissen, wann und wie sie die einzelnen Tools nutzen können, die Anbieter wie Notion, Figma oder Stripe bereitstellen. Der herkömmliche Prozess des Zusammenstellens von technischen Dokumenten zum Aufbau einer traditionellen API-Einbindung wird übersprungen. Die Kund/-innen interagieren mit Systemen unter Verwendung natürlicher Sprache als Teil einer Konversation oder eines Workflows.

Cursor und Claude Code sind MCP-Clients bzw. LLM-„Frontends“, die als Endbenutzer-Agenten fungieren. Sie konvertieren Anfragen in natürlicher Sprache in Call-to-Actions („Tools“), die von verschiedenen Dienstleistern, den sogenannten MCP-Servern, angeboten werden (z. B. Notion, Stripe oder Figma).

Anfang dieses Jahres bekam Notion erste Anfragen für einen MCP-Server. Wir haben von großen Unternehmen gehört, die KI-gestützte Workflows in ihre Wissensarbeits- und Produktentwicklungsprozesse einbinden. Wir haben auch von einzelnen Toolmakern, Entwickler/-innen und Notion-Botschafter/-innen gehört, die sich eine einfache Lösung gewünscht haben, um Daten in Notion zu integrieren und mit ihren Workspaces von vertrauten LLM-Tools wie Cursor und Claude Desktop aus zu interagieren.

Als ersten Machbarkeitsnachweis wollten wir die bestehenden API-Funktionen von Notion als durch KI aufrufbare Aktionen bereitstellen, um zu zeigen, wie das Tools-Modell die Produktivität in agentenbasierten Workflows ermöglicht.

Wir haben Anfang April mit der Veröffentlichung eines notion-mcp-Servers zum Herunterladen begonnen. Er konnte in Cursor oder Claude Desktop installiert werden (wozu allerdings technisches Fachwissen erforderlich war). In die Einrichtung war das Erstellen einer neuen Notion API-Einbindung und entweder das Kopieren des API-Schlüssels in die MCP-Kopfzeilen oder das Erstellen eines Docker-Images eingeschlossen. Einmal konfiguriert, ermöglichte er Abläufe wie die Erstellung von Seiten in Notion aus dem KI-Agenten-Chat.

Hinter den Kulissen analysierte die Bibliothek Notions öffentliche OpenAPI-Spezifikation, eine formale Beschreibung der verfügbaren API-Endpunkte und ihrer Schnittstellen. Diese Datei wurde verarbeitet, wobei MCP-Tool-Calls in HTTP-API-Calls an Notions öffentliche API unter Verwendung Ihres konfigurierten API-Schlüssels umgewandelt werden. Jeder API-Endpunkt ist einem MCP-Tool auf dem Server 1:1 zugeordnet. Der MCP-Server hat Anfragen vom MCP-Client empfangen und sie in API-Calls übersetzt, die für deinen Download personalisiert sind.

Obwohl die Einführung schwierig und die Funktionalität begrenzt war, wollten wir möglichst schnell handeln, um unseren Benutzer/-innen etwas an die Hand zu geben. Das Feedback der ersten Anwender/-innen ergab zwei wichtige Erkenntnisse: Die technische Hürde war zu hoch für eine breite Akzeptanz und die 1:1-API-Zuordnung führte zu suboptimalen Erfahrungen für KI-Agenten, z. B. zu einem hohen Verbrauch von Kontext-Token bei der Arbeit mit hierarchischen Blockdaten in JSON.

Diese Erkenntnisse haben unsere nächste Iteration geprägt – wir haben hart daran gearbeitet, eine leistungsstarke Kombination bestehender und neuer Tools für alle zugänglich zu machen und so Notions Wert als vernetzten Workspace zu vertiefen. Stell dir vor, du kannst von einem Anforderungsdokument in Notion zu einem funktionierenden Prototypen in Cursor wechseln, den Status von Aufgaben nebenbei aktualisieren und die Projektbeteiligten auf dem Laufenden halten und das alles, ohne deinen Code-Editor zu verlassen.

Die wichtigste Erkenntnis: KI-Agenten-Tools lassen sich jetzt noch einfacher in deinen Notion Workspace einbinden und ermöglichen so ein intuitiveres Agentenerlebnis durch:

• Das Hosting unseres eigenen MCP-Servers mit einer schnellen Entwicklungsschleife unter Verwendung unserer vorhandenen Codebasis und internen Tools. Notion kann schnell Verbesserungen liefern, ohne dass Benutzer/-innen aktualisierte Pakete herunterladen müssen.

• Die Erstellung einer einzigen zentralen Einbindung, die eine maßgeschneiderte Suite von Tools bereitstellt, die für KI-Agenten optimiert sind – keine HTTP-Calls der API. Wir können RESTful-Web-API-Praktiken überspringen und „private“ Funktionsabschnitte mit LLM-freundlichen Beschreibungen bereitstellen, die nur über den MCP-Server zugänglich sind, um ein angenehmes Agentenerlebnis zu ermöglichen.

Jetzt durchläuft jede/-r Benutzer/-in einen „One-Click“-OAuth-Autorisierungsablauf, um sich sicher mit derselben öffentlichen Einbindung zu verbinden. Sie installieren es in ihrem Workspace und entscheiden, welche Seiten oder Datenbanken geteilt werden sollen.

Nach erfolgreicher Anbindung wird der Datenfluss wieder zurück zu dem Tool geleitet, das sie verwendet haben (wie z. B. Cursor). Unser MCP-Server verwaltet Sitzungen und speichert der API-Token aus dem OAuth-Austausch sicher, um sich bei Tool-Calls mit der öffentlichen Notion-API zu authentifizieren.

Wir haben eng mit dem Cursor-Entwicklungsteam zusammengearbeitet, um eine angenehme OAuth-Verbindung mit streambarem HTTP zu priorisieren. Wir unterstützen auch SSE (Server-Sent Events) für die Kompatibilität mit mehr Clients, da es ein weiteres wichtiges Transportprotokoll ist, das für MCP empfohlen wird.

Neben dem Tech-Stack und dem Hosting mussten wir auch entscheiden, welche KI-Tools wir anbieten. Unser Ansatz: Zusammenarbeit mit dem Team, das den In-App-Notion-Agenten entwickelt, um AI-First-Tools vorzugsweise über vorhandene /v1/ API-Endpunkte bereitzustellen.

Um das Set an MCP-Tools zu erstellen, haben wir zwei Betriebsarten unter der Oberfläche kombiniert:

• Notion-Agent-orientierte Tools. Beispielsweise sind Create-Pages und Update-Pages neue, grundlegende Umschreibungen bestehender Create & Update Page APIs, die Schnittstellen bieten, die für eine KI-Agentenkonversation sinnvoller sind als eine herkömmliche, starre Web-API.

  • Entwickelt mit dem Notion-angehauchten Markdown, mit Beschreibungen und Antworten für Tools, die auf agentische Workflows zugeschnitten sind, anstatt auf deterministische, strukturierte JSON für Backend-Einbindungen.

  • Markdown bietet eine effiziente Inhaltsdichte pro LLM-Token und erfordert weniger Interaktionen mit Tools und geringere Kosten als der Open-Source-MCP-Server für gängige Anwendungsfälle.

  • Auch hier passt das Quick-Find-Tool. Wir haben die bestehende v1-Such-API offengelegt, um einfache Anwendungsfälle oder Konten ohne aktivierte Notion-KI abzudecken. Doch das Hauptsuchtool unterstützt die semantische Suche über Fragen, indem es Seiten in deinem Notion-Workspace sowie über zehn verbundene Apps von Drittanbietern aufdeckt!

• Bestehende API-Tools. Ausgehend vom Erfolg des Open-Source-MCP-Servers haben wir Funktionslücken geschlossen, indem wir MCP-Tools hinzugefügt haben, die vorhandene v1-APIs umschließen.

  • Zum Beispiel die API-Funktion des Create-Comment-Tools v1, ergänzt um KI-freundliche Tool-Beschreibungen, um grobe Kanten des Open-Source-Pakets zu vermeiden.

  • Diese Prompts geben deinem MCP-Client Kontext, wann und wie jedes Tool verwendet wird.

Diese kombinierte Strategie bietet umfangreiche Funktionen und stellt gleichzeitig sicher, dass Details wie Notions URLs und IDs nahtlos über Tool-Calls hinweg in deinem Chatfenster funktionieren.

Die Beta-Version von Notion-MCP gab uns die Möglichkeit, eine neue Art der Darstellung von Seiteninhalten zu testen, die für KI-Agenten viel einfacher zu erstellen, zu bearbeiten und anzuzeigen ist. Wir waren der Wegbereiter, eine verbesserte, an Notion „angelehnte“ Markdown-Spezifikation zu entwickeln, sowie eine leistungsstarke Markup-Sprache, die auf Notions breites Set an Blöcken zugeschnitten ist.

Wenn du uns schon eine Weile folgst, erinnerst du dich vielleicht an unseren Blogbeitrag aus dem Jahr 2022 über die Entwicklung der Notion-API. Damals haben wir Markdown zugunsten von JSON abgelehnt, um Ausdrucksstärke wie Rich-Text-Farben, Datenbanken und andere Notion-spezifische Bearbeitungen zu ermöglichen, die CommonMark Markdown nicht modellieren kann.

Drei Jahre später haben wir von den Herausforderungen gehört, mehrere API-Anfragen zu stellen, um mit Block-Kindern in einem hierarchischen JSON-Format zu arbeiten. Wir sind zurück zu Markdown gekommen, um Funktionsgleichheit mit Notion-Blöcken einzuführen und haben diesen Ansatz ausschließlich in unserem Remote MCP-Server getestet.

Hier ist ein kleiner Einblick in die Markdown-Spezifikation ganz nach Notion-Art:

Hervorhebungen

Spalten

Seiten

Datenbanken

Weitere Details findest du in den Tool-Beschreibungen, die über den MCP-Server zugänglich sind. Du kannst sogar deinen KI-Agenten im Chat bitten, die mit Notion erstellten Markdown-Spezifikationen für dich zusammenzufassen! Anderenfalls überlasse uns die Implementierungsdetails und beschreibe in natürlicher Sprache, was du auf einer Seite hinzufügen oder bearbeiten möchtest – lasse das LLM die Arbeit machen.

Dieser Launch ist nur der Anfang unserer Reise, Notion zum ultimativen Drehkreuz für KI-gestützte Wissensarbeit zu machen. Während wir unsere MCP-Funktionen weiter ausbauen, werden wir uns weiterhin auf das konzentrieren, was am wichtigsten ist: leistungsstarke Tools für alle zugänglich zu machen, unabhängig von technischer Expertise.

Wir arbeiten auch weiterhin mit Cursor und anderen Teams zusammen, um neue Konventionen voranzutreiben, die MCP einfacher auffindbar, sicherer und zuverlässiger machen, wie z. B. Marktplätze für vertrauenswürdige MCP-Server und -Clients und Servererkennungsprotokolle.

Wir sind gespannt, was du mit Notion MCP kreieren wirst! Teile uns mit, was du auf Social Media unter @NotionHQ erstellst.