Einrichtung
Um einen KI-Assistenten mit Waafir zu verbinden, genügt eine URL: Fügen Sie sie in Ihren Assistenten ein und melden Sie sich bei Waafir an, wenn er danach fragt. Es muss kein Token erstellt oder kopiert werden. Diese Seite behandelt die Anmeldung, den Schritt zum Hinzufügen eines Servers für jeden Assistenten und wie Sie sich stattdessen mit einem persönlichen Zugriffstoken verbinden, wenn sich ein Assistent nicht anmelden kann.
Die Grundlagen
Die URL. Eine einzige URL bedient jedes Waafir-Tool:
https://app.waafir.io/api/mcp/waafirAdd-ons → Konfiguration → KI-Assistenten zeigt die URL für Ihre Bereitstellung
mit einer Kopierschaltfläche an. Ersetzen Sie https://app.waafir.io, wenn Sie
eine andere Bereitstellung nutzen.
Anmeldung. Wenn Ihr Assistent die URL zum ersten Mal verwendet, öffnet er Waafir in Ihrem Browser. Melden Sie sich wie gewohnt an und prüfen Sie dann den Zustimmungsbildschirm:
- In welcher Organisation der Assistent arbeitet, falls Sie mehr als einer angehören;
- Welche Datenräume er erreichen darf: alle oder nur die von Ihnen ausgewählten;
- Was er tun darf: Lesen, Schreiben oder Admin, niemals mehr, als Ihre eigene Rolle erlaubt, und ob er Dokumente signieren oder an Personen außerhalb Ihrer Organisation senden darf;
- Bestätigen, dass Sie es sind. Wenn Sie die Zwei-Faktor-Authentifizierung eingerichtet haben, fragt jede Genehmigung zuerst nach Ihrem Code, so wie beim Erstellen eines Tokens.
Genehmigen Sie, und der Browser übergibt Sie wieder an den Assistenten. Die Verbindung erscheint unter Add-ons → Konfiguration → KI-Assistenten, wo Sie sehen können, worauf sie zugreifen kann, und sie widerrufen können. Siehe Verbindungen.
Unverified app "…". Ein Assistent, der sich über eine von ihm
kontrollierte Webadresse ausweist, wird mit dieser Adresse angezeigt, etwa
claude.ai. Einer, der sich mit einem selbst gewählten Namen registriert hat,
wird als Unverified app "<its name>" angezeigt: Waafir kann nicht bestätigen,
wer ihn erstellt hat, genehmigen Sie ihn also nur, wenn Sie die Verbindung
selbst gestartet haben.
Was die Tool-Liste zeigt. Tool-Namen beginnen mit ihrem Bereich:
dataroom_, esign_, redact_ und translate_. Die Liste zeigt nur die
Tools, die Ihre Verbindung und Ihre Organisation nutzen dürfen: Einer
schreibgeschützten Verbindung werden keine Schreib-Tools angezeigt, und die
E-Signatur-Tools erscheinen nur, wenn Ihre Organisation das
E-Signatures-Add-on oder ein aktives Abonnement besitzt. Eine Verbindung listet
außerdem die Tools auf, die eine Berechtigung benötigen, die Sie nicht erteilt
haben, etwa das Signieren oder das Senden an Personen außerhalb Ihrer
Organisation. Ruft der Assistent eines davon auf, lehnt Waafir den Aufruf ab,
und der Assistent bittet Sie erneut um Genehmigung, diesmal mit dieser
angebotenen Berechtigung. Ein Token kann nicht erneut fragen, daher lässt seine
Liste diese Tools weg. Ein nicht aufgeführtes Tool wird trotzdem mit Angabe des
Grundes abgelehnt, falls ein Assistent es dennoch aufruft.
Ihren Assistenten verbinden
Jeder der folgenden Abschnitte nennt den Schritt zum Hinzufügen eines Servers im jeweiligen Assistenten und verlinkt auf dessen Dokumentation (jeder Link zuletzt am 23. Oktober 2026 geprüft). Keiner dieser Assistenten wurde bisher mit der Waafir-Anmeldung getestet, daher führt jeder Abschnitt die Token-Alternative mit auf.
Claude (claude.ai und Claude Desktop)
Noch nicht von Waafir getestet. Öffnen Sie Customize → Connectors, wählen Sie Add → Add custom connector, geben Sie einen Namen ein, fügen Sie die URL ein und fahren Sie fort. Lassen Sie die Anmeldung aktiviert und melden Sie sich bei Waafir an, wenn Claude danach fragt. Um ihn in einem Chat zu nutzen, aktivieren Sie ihn unter + → Connectors. Bei einem Team- oder Enterprise-Plan fügt ein Eigentümer Connectors unter Organization settings → Connectors hinzu. (Anleitung von Claude)
Funktioniert die Anmeldung nicht, fügen Sie stattdessen einen Request-Header
Authorization: Bearer <token> mit einem Token hinzu (siehe
Stattdessen mit einem Token verbinden).
ChatGPT
Noch nicht von Waafir getestet. ChatGPT erreicht Remote-MCP-Server je nach App an unterschiedlichen Stellen; öffnen Sie in der Desktop-App Settings → MCP servers → Add server, fügen Sie die URL ein und melden Sie sich bei Waafir an, wenn Sie dazu aufgefordert werden. (Anleitung von OpenAI)
Kann sich ChatGPT nicht anmelden, verwenden Sie stattdessen ein Token.
Claude Code
Noch nicht von Waafir getestet.
claude mcp add --transport http waafir https://app.waafir.io/api/mcp/waafirFühren Sie dann /mcp in Claude Code aus (oder claude mcp login waafir in
Ihrer Shell) und melden Sie sich im Browser bei Waafir an. Fügen Sie
--scope user hinzu, um ihn in jedem Projekt zu nutzen. Add-ons → Konfiguration → KI-Assistenten hält diesen Befehl kopierbereit vor.
(Anleitung von Claude Code)
Cursor
Noch nicht von Waafir getestet. Fügen Sie die URL zu .cursor/mcp.json hinzu
(oder zu ~/.cursor/mcp.json für jedes Projekt) und melden Sie sich bei Waafir
an, wenn Cursor danach fragt:
{
"mcpServers": {
"waafir": {
"url": "https://app.waafir.io/api/mcp/waafir"
}
}
}Kann sich Cursor nicht anmelden, fügen Sie den Token-Header hinzu, der unter Stattdessen mit einem Token verbinden gezeigt wird.
VS Code
Noch nicht von Waafir getestet. Führen Sie MCP: Add Server über die
Befehlspalette aus, wählen Sie HTTP, fügen Sie die URL ein und geben Sie
ihm die ID waafir. Melden Sie sich bei Waafir an, wenn VS Code danach fragt.
(Anleitung von VS Code)
Gemini CLI
Noch nicht von Waafir getestet.
gemini mcp add --transport http waafir https://app.waafir.io/api/mcp/waafirFühren Sie dann /mcp auth waafir aus und melden Sie sich im Browser an. Die
Anmeldung benötigt einen lokalen Browser und funktioniert daher über die
meisten Remote-SSH-Sitzungen nicht: Verwenden Sie dort ein Token.
(Anleitung von Gemini CLI)
Codex
Noch nicht von Waafir getestet.
codex mcp add waafir --url https://app.waafir.io/api/mcp/waafir
codex mcp login waafirStattdessen mit einem Token verbinden
Verwenden Sie ein persönliches Zugriffstoken,
wenn sich ein Assistent nicht anmelden kann, oder für ein Skript. Jede Anfrage
überträgt das Token als Bearer-Token im Authorization-Header:
Authorization: Bearer waafir_pat_...Committen Sie niemals ein echtes Token in eine gemeinsam genutzte Datei oder ein Repository; behandeln Sie es wie ein Passwort. Add-ons → Konfiguration → API-Token bietet ein kopierbereites Snippet.
Bereichsserver. Neben waafir werden weiterhin vier Bereichsserver
bereitgestellt, damit eine bestehende Konfiguration weiter funktioniert. Jeder
listet nur die Tools seines eigenen Bereichs auf, auf dieselbe Weise gefiltert,
und behält die Tool-Namen, die er schon immer hatte (list_files statt
dataroom_list_files). Sie benötigen sie nicht, wenn Sie sich mit waafir
verbinden:
| Server | URL |
|---|---|
waafir-redact | https://app.waafir.io/api/mcp/waafir-redact |
waafir-translate | https://app.waafir.io/api/mcp/waafir-translate |
waafir-dataroom | https://app.waafir.io/api/mcp/waafir-dataroom |
waafir-esign | https://app.waafir.io/api/mcp/waafir-esign |
Es gibt keinen reinen /api/mcp-Endpunkt: Das Segment mit dem Servernamen
ist erforderlich, und eine Anfrage ohne dieses gibt einen 404 zurück.
waafir-esign ist ein kostenpflichtiges Angebot:
Ohne das E-Signatures-Add-on oder ein aktives Abonnement antwortet seine URL mit
einem ADDON_NOT_PURCHASED-Fehler. Über waafir sieht dieselbe Organisation
die esign_-Tools einfach nicht.
Claude Code. Legen Sie das Token zuerst in einer Umgebungsvariablen ab, damit es nicht in Ihrem Shell-Verlauf landet:
export WAAFIR_PAT=... # the token you copied at issuance
claude mcp add --transport http waafir https://app.waafir.io/api/mcp/waafir \
--header "Authorization: Bearer $WAAFIR_PAT"Um die Einrichtung mit einem Projekt zu teilen, legen Sie denselben Eintrag in
dessen .mcp.json ab. Claude Code expandiert ${WAAFIR_PAT} aus der Umgebung
jeder Person, sodass die Datei ohne das Token committet werden kann:
{
"mcpServers": {
"waafir": {
"type": "http",
"url": "https://app.waafir.io/api/mcp/waafir",
"headers": {
"Authorization": "Bearer ${WAAFIR_PAT}"
}
}
}
}Die Konfigurationsdatei von Claude Desktop. claude_desktop_config.json
startet lokale Server: Jeder Eintrag ist ein auszuführender command, keine
Remote-url. Um Waafir aus dieser Datei zu erreichen, führen Sie die
mcp-remote-Bridge aus (sie
benötigt Node.js), die an den Remote-Server weiterleitet und Ihr Token als
Header hinzufügt:
{
"mcpServers": {
"waafir": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://app.waafir.io/api/mcp/waafir",
"--header",
"Authorization:${WAAFIR_AUTH}"
],
"env": {
"WAAFIR_AUTH": "Bearer YOUR_WAAFIR_PAT"
}
}
}
}Halten Sie das Argument Authorization:${WAAFIR_AUTH} frei von Leerzeichen und
starten Sie Claude Desktop anschließend neu.
Cursor und andere Clients, die eine URL und Header akzeptieren.
{
"mcpServers": {
"waafir": {
"url": "https://app.waafir.io/api/mcp/waafir",
"headers": {
"Authorization": "Bearer YOUR_WAAFIR_PAT"
}
}
}
}Ein Bereichsserver wird auf dieselbe Weise hinzugefügt, wobei der Eintragsschlüssel und die URL geändert werden.
Ein Tool aufrufen
Nach dem Verbinden listet Ihr Client die Tools des Servers auf (ein MCP
tools/list) und ruft sie in Ihrem Namen auf. Sie rufen Tools nicht von Hand
auf — Sie bitten den KI-Client, etwas zu tun („liste die Dateien in diesem
Datenraum auf“, „übersetze diesen Absatz ins Französische“), und er wählt das
richtige Tool aus und ruft es auf, wobei er die in der Referenz des jeweiligen
Servers dokumentierten Argumente übergibt. Die Tool-Verträge finden Sie in den
Referenzen zu waafir-redact,
waafir-translate,
waafir-dataroom und
waafir-esign.
Wenn etwas schiefgeht
Fehler treten auf zwei verschiedenen Ebenen auf, und sie sehen nicht gleich aus. Dies falsch zu handhaben ist hier der häufigste Integrationsfehler: Ein Client, der nur nach dem HTTP-Status verzweigt, übersieht stillschweigend jeden Fehler der zweiten Art.
Ebene 1 — die Anfrage wurde abgelehnt, bevor ein Tool lief
Dies sind echte HTTP-Fehlerstatus mit einem Fehlerkörper in JSON-RPC-Form. Sie bedeuten, dass die Anfrage überhaupt kein Tool erreicht hat:
-
404 — Unbekannter MCP-Server. Das Servernamen-Segment der URL ist keiner von
waafir,waafir-redact,waafir-translate,waafir-dataroomoderwaafir-esign— meist ein Tippfehler oder ein reines/api/mcpohne Servernamen. Korrigieren Sie die URL. -
402 — Add-on nicht erworben. Der Server ist ein kostenpflichtiges Angebot (derzeit:
waafir-esign), und Ihre Organisation besitzt weder das Add-on noch ein aktives Abonnement. Ein Org-Admin kann das Add-on oder einen Plan in den Abrechnungseinstellungen erwerben. Eine nicht berechtigte Organisation kann die Tools des Servers nicht einmal auflisten.waafirantwortet nie mit 402: Es blendet die kostenpflichtigen Tools stattdessen aus, und ein Aufruf eines davon wird auf Ebene 2 mitQUOTA_EXCEEDEDund einer Meldung abgelehnt, die dieses Tool nennt und ebenfallsADDON_NOT_PURCHASEDenthält. -
401 — Nicht authentifiziert. Die Anmeldedaten fehlen, sind fehlerhaft, widerrufen oder abgelaufen. Bei einer Verbindung melden Sie sich von Ihrem Assistenten aus erneut an: Die meisten Assistenten tun dies selbst, wenn sie den 401 sehen, und eine Verbindung, die widerrufen wurde oder 30 Tage lang ungenutzt war, erfordert eine neue Anmeldung. Bei einem Token prüfen Sie, ob der
Authorization-Header vorhanden ist und das Token unter Add-ons → Konfiguration → API-Token noch aktiv ist; stellen Sie ein neues aus, wenn es widerrufen wurde oder abgelaufen ist. Eine Bereitstellung, die älter als dieses Verhalten ist, beantwortet ein fehlendes oder fehlerhaftes Token stattdessen mit 403CSRF validation failed: missing Origin; auf dieser Oberfläche bedeutet auch das, dass das Token fehlt oder fehlerhaft ist. -
403 — Verboten. Die Anmeldedaten wurden schon am Eingang abgewiesen: Es wurde eine angemeldete Browsersitzung statt einer Verbindung oder eines PAT verwendet (Sitzungen werden auf dieser Oberfläche nicht akzeptiert), oder Ihre Organisation erzwingt eine IP-Allowlist, und die Anfrage kam von einer Adresse außerhalb davon.
-
429 — Zu viele Anfragen. Sie haben ein MCP-Ratenlimit erreicht. Nichts davon ist an Ihre IP-Adresse oder Ihre Organisation gebunden — Ihr Budget ist das Ihres Tokens, sodass ein Kollege in derselben Organisation und ein zweiter Client im selben Netzwerk es nicht verbrauchen. Das Limit beträgt 60 Anfragen pro Minute und Token. Es wird gezählt, bevor das Token nachgeschlagen wird, sodass auch ein fehlerhaftes, widerrufenes oder abgelaufenes Token es verbraucht, und Aufrufe desselben Tokens an die Waafir-API außerhalb von MCP zählen gegen dieselben 60. Die 60 einer angemeldeten Verbindung werden außerdem pro Verbindung gezählt, sodass das neue Token, das Ihr Assistent beim Erneuern seiner Anmeldung erhält, nicht mit frischen 60 beginnt.
Die Antwort enthält keinen
Retry-After-Header und keinen unterscheidenden Code — jeder 429 auf dieser Oberfläche sieht gleich aus —, also warten Sie nach einem eigenen Zeitplan ab, statt in einer Schleife erneut zu versuchen. Reicht ein Token nicht an Spielraum aus, stellen Sie ein zweites aus: Das Limit gilt pro Token.
Ebene 2 — ein Tool lief und lehnte ab
Hier finden die meisten Ablehnungen statt, und es ist kein HTTP-Fehler.
Die HTTP-Antwort ist 200, und der JSON-RPC-Umschlag ist ein
Erfolgs-Umschlag. Der Fehler wird im Tool-Ergebnis übertragen, das
isError: true setzt und dessen Textinhalt lautet:
{ "error": { "code": "CONFLICT", "message": "…" } }Verzweigen Sie nach error.code. Die Codes sind:
| Code | Bedeutung |
|---|---|
INVALID_ARGUMENT | Ein Argument fehlt, ist fehlerhaft oder keine gültige ID — korrigieren Sie es und versuchen Sie es erneut |
FORBIDDEN | Das Token ist gültig, aber für diesen Aufruf nicht zugelassen |
NOT_FOUND | Kein solcher Datensatz, oder er gehört nicht Ihnen |
CONFLICT | Verstanden und zulässig, aber der Datenraum befindet sich nicht in einem Zustand, in dem es ausgeführt werden kann |
TOO_LARGE | Die Eingabe überschreitet eine Größengrenze — teilen Sie sie auf |
QUOTA_EXCEEDED | Ein bemessenes Kontingent ist aufgebraucht; jemand muss etwas kaufen oder upgraden |
UPSTREAM_ERROR / UNAVAILABLE | Ein vorübergehender Fehler in einem nachgelagerten System — später erneut versuchen |
INTERNAL | Ein unerwarteter Fehler — nicht erneut versuchen, eskalieren |
Zwei davon sorgen oft für Überraschungen:
FORBIDDENbei einem zu niedrigen Bereich. Einerread-Verbindung oder einemread-Token werden keine Schreib-Tools angezeigt, aber ein Client, der dennoch eines aufruft, wird vom Tool abgelehnt, sodass dies hier alsFORBIDDENin der Nutzlast ankommt — nicht als HTTP 403. Dasselbe gilt für ein Token, das auf bestimmte Datenräume beschränkt ist und einen Datenraum außerhalb seiner Allowlist alsdataroom_idangibt. Die meisten Tools, die eine Datei- oder Ordner-ID entgegennehmen, antworten für ein Element in einem solchen Datenraum stattdessen mitNOT_FOUND, genau wie für eine ID, die nicht existiert. Melden Sie sich von Ihrem Assistenten aus erneut an und erteilen Sie den richtigen Bereich oder die richtigen Datenräume, oder stellen Sie ein Token mit dem richtigen Bereich aus.CONFLICT. Der Aufruf wurde verstanden und ist zulässig, aber der Datenraum befindet sich nicht in einem Zustand, in dem er ausgeführt werden kann — ein bereits vergebener Ordnername, eine Datei, deren Namen inzwischen eine aktive Datei beansprucht hat, oder eine Wiederherstellung, deren Container noch gelöscht ist oder deren Upload nie abgeschlossen wurde. EinCONFLICTist kein Autorisierungsproblem, und eine erneute Anmeldung oder Neuausstellung des Tokens hilft nicht; die Meldung nennt den blockierenden Datensatz, sofern es einen gibt, sodass Sie darauf reagieren und es erneut versuchen können. Diewaafir-dataroom-Referenz listet die Konflikte auf, die jedes Tool zurückgeben kann.
Eine Datei, die noch geprüft wird. Waafir prüft jede neu hochgeladene Datei
und jede neue Version, bevor es den Inhalt ausliefert. Bis dahin antwortet ein
Tool, das den Inhalt der Datei liest, mit UNAVAILABLE,
error.reason: "ACTIVATION_PENDING" und der Meldung
This file is still being checked. Try again shortly. Das ist vorübergehend:
Rufen Sie das Tool nach kurzer Wartezeit erneut auf.
Eine eindeutige Ablehnung auf einer der beiden Ebenen ist das erwartete, sichere Ergebnis eines Aufrufs, den Waafir nicht ausführt — die Anfrage schlägt fehl, statt stillschweigend weniger zu tun, als Sie verlangt haben.