MCP & KI-Integration

Das Model Context Protocol (MCP) erlaubt KI-Assistenten, eure Wissensdatenbank zu lesen und (mit passenden API-Key-Scopes) zu ändern – z. B. Suche, Dokumente listen, Dokumente anlegen oder aktualisieren.

Orimora bietet zwei MCP-Transporte:

1. HTTP-Endpunkt unter /api/mcp — empfohlen für Remote-Zugriff. Nutzt den MCP Streamable HTTP Transport. Authentifizierung via API-Key als Bearer-Token.
2. stdio-Server im Repository — für lokale Entwicklung. Der MCP-Client startet yarn mcp.

Wer das aktivieren kann

MCP zu aktivieren ist eine Team-Admin-Aktion. Es ist über die Berechtigung developer.mcp abgesichert, die das Ein-/Ausschalten des MCP-Endpunkts und die Verwaltung verbundener Apps steuert. Standardmäßig hat nur die Gruppe Admins diese Berechtigung — die Gruppen Editors, Members und Viewers nicht.

Wenn du den Bereich MCP-Server unter Einstellungen → Entwickler also nicht siehst, fehlt dir diese Berechtigung: Bitte eine:n Workspace-Admin, MCP zu aktivieren oder deiner Gruppe unter Einstellungen → Gruppen die Capability developer.mcp zu geben.

Was du brauchst

• Eine:n Team-Admin (oder die Berechtigung developer.mcp), um MCP einzuschalten — siehe oben.
• Für Cursor, Claude Desktop oder Obsidian: nichts weiter — diese verbinden sich mit einem persönlichen API-Key (kb_…), den du unter Einstellungen → Entwickler erstellst.
• Für die Claude-Mobile-App oder claude.ai-Custom-Connectors: dein Orimora muss unter einer öffentlichen https://-Adresse erreichbar sein. Smartphones erreichen kein localhost, und der OAuth-Login erfordert HTTPS. Beim Self-Hosting setzt du das über APP_URL (siehe Hinweis weiter unten); bei gehostetem Orimora ist das bereits so. Sonst nichts zu konfigurieren — Login und Discovery sind eingebaut, kein Key zum Kopieren.

In drei Schritten einrichten

1. MCP einschalten. In der Web-App: Einstellungen → Entwickler → MCP-Server (HTTP) → aktivieren. Die Seite zeigt danach deine Verbindungs-URL ({APP_URL}/api/mcp) und die Kopier-Buttons.
2. Client verbinden. Folge dem passenden Abschnitt unten:
   • Cursor → HTTP-Endpunkt mit API-Key.
   • Claude Desktop → Bridge oder Custom Connector.
   • Claude Mobile / claude.ai → OAuth-Custom-Connector — du loggst dich ein und bestätigst, kein Key zum Kopieren.
   • Beliebiger anderer MCP-Client → Beliebiger MCP-Client.
3. Prüfen und Zugriff verwalten. Nach dem Verbinden kann dein Assistent suchen und — mit Schreibrechten — Dokumente bearbeiten. Per OAuth verbundene Apps erscheinen unter Einstellungen → Entwickler → Autorisierte Apps mit Scope und letztem Zugriff; dort kannst du jede App widerrufen, um den Zugriff sofort zu beenden.

Tipp

Unsicher, welcher Client? Cursor und Claude Desktop sind mit einem API-Key am schnellsten eingerichtet. Die Claude-Mobile-App nutzt den Login-und-Bestätigen-Flow (OAuth) und braucht eine öffentliche HTTPS-Adresse.

Voraussetzungen

• Derselbe Stack wie bei Installation: Node.js, Yarn, PostgreSQL und eine funktionierende .env mit mindestens DATABASE_URL (und den übrigen in der Konfiguration beschriebenen Secrets).
• Ein API-Key aus der Web-App: Einstellungen → Entwickler. Den vollständigen Token einmal kopieren (Format kb_…). Der MCP-Server prüft ihn wie die REST-API gegen die Datenbank.

Achtung

Behandle ORIMORA_API_KEY wie ein Passwort. Wer den Key und DB-Zugang hat, kann im Rahmen der Key-Scopes im Namen dieses Team-Benutzers handeln.

Option 1: HTTP-Endpunkt (empfohlen)

Der HTTP-Endpunkt liegt unter {APP_URL}/api/mcp (z. B. https://deine-domain.de/api/mcp) und muss pro Team aktiviert werden: Einstellungen → Entwickler → MCP-Server (HTTP). Nur Admins können den Schalter setzen.

Authentifizierung via Bearer-Token — dieselben API-Keys wie unter Einstellungen → Entwickler.

Schnellstart (Cursor + gehostetes Orimora)

1. In der Web-App Einstellungen → Entwickler öffnen und MCP-Server (HTTP) aktivieren.
2. Unter API-Keys einen Key mit passenden Scopes anlegen (write, wenn Tools Dokumente ändern sollen). Den vollständigen Token einmal kopieren — Präfix kb_.
3. Auf derselben Seite URL kopieren und Cursor-MCP-JSON kopieren nutzen (sichtbar, wenn MCP an ist). Im JSON YOUR_API_KEY durch den echten kb_…-Token ersetzen.
4. Den mcpServers-Eintrag in die Cursor-MCP-Konfiguration einfügen:
   • Benutzerweit: ~/.cursor/mcp.json (macOS/Linux) bzw. der Pfad unter Cursor → Einstellungen → MCP für dein Betriebssystem.
   • Nur ein Repo: .cursor/mcp.json im Repository-Root.
5. Cursor neu starten oder MCP neu laden, damit der Server erscheint.

Tipp

Die Entwickler-Seite nutzt immer euer echtes APP_URL für die Endpunkt-URL. Wenn die Zwischenablage im Browser blockiert ist, JSON markieren und manuell kopieren.

Cursor (HTTP) — Konfig-Snippet

{
  "mcpServers": {
    "orimora": {
      "url": "https://deine-domain.de/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

https://deine-domain.de durch eure Instanz-URL und YOUR_API_KEY durch den vollständigen kb_…-Key ersetzen.

Claude Desktop (HTTP via mcp-remote-Bridge)

Die Config-Datei von Claude Desktop (claude_desktop_config.json) spricht nur stdio. Um aus ihr heraus den Orimora-HTTP-Endpunkt zu erreichen, leiten wir über die mcp-remote-Bridge – ein kleines Node-Helper-Paket, das zwischen stdio (was Claude spricht) und HTTP+Bearer (was Orimora spricht) übersetzt.

In Claude Desktop Einstellungen → Entwickler → Konfig bearbeiten öffnen (oder die Datei direkt – macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) und einfügen:

{
  "mcpServers": {
    "orimora": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://deine-domain.de/api/mcp",
        "--header",
        "Authorization:${AUTH}"
      ],
      "env": {
        "AUTH": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Hinweise:

• Token in env.AUTH ablegen und per ${AUTH} in --header referenzieren. So steht der Key in der Prozess-Umgebung, nicht auf der Kommandozeile (kein Leak in ps).
• Kein Leerzeichen zwischen Authorization: und ${AUTH} – manche mcp-remote-Versionen verwerfen in --header alles nach dem ersten Space.
• Nach dem Bearbeiten Claude Desktop komplett beenden (⌘Q auf macOS) und neu starten. Nur das Fenster schließen genügt nicht.
• Auf macOS erbt Claude Desktop nicht zwingend den Shell-PATH. Falls npx nicht gefunden wird, absoluten Pfad eintragen (which npx).

Bridge vorab testen (ohne Claude-Config anzufassen):

npx -y mcp-remote https://deine-domain.de/api/mcp \
  --header "Authorization:Bearer kb_…"

Startet der Prozess ohne 401, funktioniert dieselbe Konfiguration auch in Claude Desktop.

Tipp

Neuere Claude-Desktop-Builds (Pro/Max) bieten Einstellungen → Connectors → Custom Connector hinzufügen, wo die HTTPS-URL und Authorization: Bearer kb_… direkt eingetragen werden können – ohne Bridge. Die Verfügbarkeit hängt von Plan und Release-Kanal ab.

Beliebiger MCP-Client

Standard MCP Streamable HTTP Requests senden:

• POST /api/mcp — MCP JSON-RPC Nachrichten
• GET /api/mcp — SSE-Stream für Server-initiierte Nachrichten
• DELETE /api/mcp — Session-Cleanup

Alle Requests erfordern den Authorization: Bearer kb_… Header.

Hinweis

Der HTTP-Endpunkt ist stateless — jeder Request erzeugt eine frische MCP-Session. Das hält den Server einfach und funktioniert mit Load Balancern.

Claude Mobile / Custom Connector (OAuth)

Die drei Flows oben nutzen einen statischen kb_…-API-Key — perfekt für Cursor, Claude Desktop und Obsidian. Die Claude-Mobile-App und claude.ai Custom Connectors erwarten stattdessen einen OAuth-2.1-Flow: Du fügst eine URL ein, ein Browser öffnet sich, du loggst dich ein und bestätigst, und die App erhält ihr eigenes Token. Orimora unterstützt das out of the box — kein API-Key zum Kopieren.

Setup:

1. Aktiviere MCP für dein Team: Einstellungen → Entwickler → MCP-Server → einschalten.
2. Füge in der Claude-App einen Custom Connector hinzu und gib deine Orimora-MCP-Endpunkt-URL ein — sie MUSS den Pfad /api/mcp enthalten, z. B. https://wiki.example.com/api/mcp (derselbe Endpunkt wie Option 1, nur ohne API-Key). Gib nicht die bare Domain ein (https://wiki.example.com) — die trifft die Startseite und liefert 405, dann startet OAuth nie. Aus dem 401 an /api/mcp entdeckt die App den OAuth-Flow automatisch via /.well-known/oauth-protected-resource.
3. Dein Browser öffnet einen Orimora-Login → Consent-Screen. Bestätige den angeforderten Zugriff (Lesen oder Lesen + Schreiben).
4. Fertig. Die App hält ein kurzlebiges Access-Token (auto-refresh), gescoped auf dein Team.

Zugriff verwalten: Jede verbundene App erscheint unter Einstellungen → Entwickler → Autorisierte Apps mit gewährtem Scope und letzter Nutzung. Widerrufen dort macht die Tokens sofort ungültig — die App muss sich neu autorisieren.

Hinweis

OAuth-Tokens sind gescoped (mcp:read / mcp:write), aber nicht auf bestimmte Sammlungen beschränkt wie der Restricted-Mode eines API-Keys — sie sehen alles im Team innerhalb ihres Scopes. Für Pro-Sammlungs-Limits einen Restricted-Mode-API-Key (Option 1) nutzen.

Achtung

Self-Hoster: Der OAuth-Issuer ist dein APP_URL — setze ihn auf deine echte öffentliche https-Origin, bevor du den Mobile-Flow nutzt (der Server warnt, wenn OAuth aktiv ist, während APP_URL noch localhost ist). Discovery wird über MCP_OAUTH_ENABLED gesteuert (Standard an).

Endpunkte & Konfiguration (Referenz)

Clients entdecken diese automatisch; hier für Betrieb und Debugging gelistet. Alle werden aus APP_URL (dem Issuer) abgeleitet:

Endpunkt	Zweck
/.well-known/oauth-protected-resource	RFC-9728 Protected-Resource-Metadata
/.well-known/oauth-authorization-server	RFC-8414 Authorization-Server-Metadata
POST /oauth/register	Dynamic Client Registration (RFC 7591)
GET/POST /oauth/authorize	Autorisierung + Consent (PKCE S256)
POST /oauth/token	Token-Ausgabe + Refresh (Rotation)
POST /oauth/revoke	Token-Widerruf (RFC 7009)

Vollständige Konfiguration (TTLs, CORS-Origins, erlaubte App-Schemes, Rate-Limit, Token-Secret) in der Konfigurations-Referenz → MCP OAuth.

Option 2: stdio-Server (lokale Entwicklung)

Für lokale Entwicklung mit direktem Datenbankzugriff:

export ORIMORA_API_KEY="kb_dein_vollständiger_token"
yarn mcp

Der Prozess nutzt stdio – er wird von einem MCP-Client als Kindprozess gestartet, nicht im Browser geöffnet.

Technisch: tsx mit tsconfig.mcp.json und src/mcp-server/index.ts (siehe Script mcp in package.json).

Cursor (stdio)

{
  "mcpServers": {
    "orimora": {
      "command": "yarn",
      "args": ["mcp"],
      "cwd": "/absoluter/pfad/zum/orimora-repo",
      "env": {
        "ORIMORA_API_KEY": "kb_…",
        "DATABASE_URL": "postgresql://user:pass@host:5432/dbname"
      }
    }
  }
}

• cwd muss das Orimora-Repo-Root sein (Module und Pfade).
• Lädt der Client eure .env, können doppelte Variablen entfallen – sonst DATABASE_URL explizit setzen.

Claude Desktop und andere (stdio)

Gleiches Muster: command, args, Arbeitsverzeichnis, Umgebung mit ORIMORA_API_KEY und DATABASE_URL.

Inhalt schreiben: Markdown ist kanonisch

create_document, update_document, append_to_document, prepend_to_document und insert_after_heading erwarten den Inhalt als Markdown über den Parameter markdown. Der Server wandelt ihn in das TipTap/ProseMirror-JSON um, das der Editor erwartet (über markdown-it → HTML → das gemeinsame TipTap-Schema).

Kein TipTap/ProseMirror-JSON über MCP senden. Die Tools exponieren kein content-Feld. Direktes Editor-JSON würde voraussetzen, dass der Client jede verwendete Extension und jedes Attribut kennt – das driftet mit der Zeit, und unbekannte Nodes werden still verworfen.

get_document spiegelt das und liefert den Inhalt nur als markdown (kein TipTap-JSON). Das hält Payloads klein und zwingt Clients in dasselbe Format auf Lese- und Schreibseite.

Markdown-Support-Matrix

Voll round-trip-fähig (Lesen und Schreiben): Überschriften (H1–H6) inkl. Heading-IDs (### Titel {#anker}), Absätze, fett, kursiv, inline code, ~~durchgestrichen~~, <u>unterstrichen</u>, Highlight (==x==), Subskript (~x~), Superskript (^x^), Footnotes ([^1]-Referenzen + [^1]: Text-Definitionen), Emoji-Shortcodes (:joy: → 😂, als Unicode gespeichert), sortierte Listen (inkl. individueller Startnummer), unsortierte Listen, verschachtelte Listen, Task-Listen (- [ ] / - [x]), Blockzitate, Codeblöcke mit Sprach-Hint, Trennlinien, GFM-Tabellen, Links sowie Bilder über externe URLs.

Aktuell nicht via MCP unterstützt (im internen Backlog):

• Definition Lists (term / : def) – werden vom Editor noch nicht gerendert; vorerst beim Schreiben vermeiden (Backlog Tier 3).
• Inline-Base64-Bilder im Markdown – werden abgelehnt. Nutze das upload_image-Tool, um ein Bild an ein Dokument anzuhängen, oder referenziere eine extern erreichbare URL.

Für die absolute Markdown-Quelle jederzeit get_document aufrufen – der zurückgegebene markdown-String ist byte-genau äquivalent zu dem, was der Editor anzeigt.

Inkrementelle Änderungen

Für bestehende Dokumente gezielte Änderungen nutzen statt Full-Rewrites:

• append_to_document(id, markdown) – hängt ein Fragment am Ende an, getrennt durch eine Leerzeile.
• prepend_to_document(id, markdown) – fügt am Anfang ein.
• insert_after_heading(id, heading, markdown) – fügt direkt nach der ersten Überschrift ein, deren Text mit heading übereinstimmt (case-insensitive, getrimmt). Liefert HEADING_NOT_FOUND, wenn keine passt – Aufrufer sollten dann auf append_to_document fallback.

Alle drei lassen bestehenden Inhalt unverändert, benötigen write-Scope plus Schreibrecht aufs Dokument und nutzen dieselbe Markdown→TipTap-Konvertierung wie create_document.

Dokumente löschen

delete_document führt einen Soft Delete aus (Dokument landet im Papierkorb, aus der App wiederherstellbar). Es ist eine zweistufige Aktion:

1. Aufruf ohne confirm – der Server antwortet mit { status: "confirm_required", preview: { title, collectionName, bodyLength, … } }, damit der Agent dem User zeigen kann, was gelöscht werden soll.
2. Zweiter Aufruf mit confirm: true – der Server legt das Dokument in den Papierkorb und liefert { status: "deleted", id, deletedAt }.

Hard-Deletes sind über MCP nicht verfügbar. Endgültiges Löschen passiert in der App über „Papierkorb leeren”.

Rechte und Restricted Mode

API-Keys haben:

• Scopes: read, write, admin – schreibende MCP-Tools brauchen wo nötig write.
• Restricted Mode: optionale Allowlists pro Sammlung und Dokument-Overrides unter Einstellungen → Entwickler → Zugriff konfigurieren. Dieselben Regeln gelten für MCP und /api/v1/.

„Second Brain” (read-only) vs. beschreibbare Collections

Typisches Agent-Setup: Eine Collection ist read-only Wissensbasis für die KI, eine andere ist Schreib-Fläche. Ein einziger API-Key reicht – Restricted Mode erlaubt per-Collection-Overrides, also kann ein Key Read-Only auf die Wissensbasis und Read+Write auf die Arbeits-Collection halten.

Für diesen Key unter Einstellungen → Entwickler → Zugriff konfigurieren:

1. Restricted Mode aktivieren.
2. Wissens-Collection auf Nur Lesen setzen.
3. Arbeits-Collection auf Lesen + Schreiben setzen.
4. Alle anderen auf Kein Zugriff.

Die MCP-Tools liefern auf jeder Collection in list_collections und auf jeder get_document-Antwort ein canWrite-Flag. Agenten sollten dieses Flag prüfen, bevor sie create_document / update_document / append_to_document / delete_document aufrufen, statt Fehlversuche zu riskieren.

Weiterführend

• REST-API Überblick — Bearer kb_… für HTTP
• Konfiguration — Umgebungsvariablen
• OpenAPI-Referenz — REST-Operationen

Kurz-Checkliste für Maintainer: internal/dev-and-mcp.md im Repository.