Musael-MCP-Server

Server

Server-URL: https://app.musael.com/api/mcp?lang=de
Transport: Streamable HTTP, zustandslose JSON-Antworten. Sende JSON-RPC-Nachrichten per POST; GET und DELETE antworten mit 405.
Servername: musael

Authentifizierung

Jede Anfrage braucht den Header Authorization: Bearer <token>. Ohne Token oder mit einem widerrufenen, abgelaufenen oder falschen antwortet der Server mit 401 und einem WWW-Authenticate-Header, der auf seine OAuth-Metadaten verweist.

OAuth-Anmeldung

Für ChatGPT, Claude, Cursor, VS Code und andere Clients, die sich per Anmeldung verbinden. Der Client entdeckt alles aus der 401-Antwort, gemäß der MCP-Autorisierungsspezifikation:

Metadaten der geschützten Ressource (RFC 9728): https://app.musael.com/.well-known/oauth-protected-resource/api/mcp
Metadaten des Autorisierungsservers (RFC 8414): https://app.musael.com/.well-known/oauth-authorization-server
Dynamische Client-Registrierung (RFC 7591): nur öffentliche Clients, ohne Secret; Weiterleitungsadressen über HTTPS, HTTP nur auf Loopback, oder ein App-Schema.
Autorisierungscode mit PKCE (nur S256). Die schreibende Person meldet sich an, wählt „Nur lesen“ oder „Lesen und hinzufügen“ sowie die Projekte und erlaubt oder bricht ab.
Zugriffstokens gelten eine Stunde; Refresh-Tokens gelten 90 Tage und wechseln bei jeder Verwendung.
Scopes: read und suggest (der schreibenden Person als „Lesen und hinzufügen“ angezeigt).

Persönliches Zugriffstoken

Für von Hand konfigurierte Clients wie Codex, Claude Code oder ein Skript. Die schreibende Person erstellt das Token in Musael unter Einstellungen → Verbundene Apps und wählt einen Namen, die Projekte, den Zugriff und das Ablaufdatum.

Tokens beginnen mit sti_ und werden einmal angezeigt; Musael speichert nur einen Hash davon.
Ein Konto kann bis zu 20 aktive Tokens haben. „Widerrufen“ schaltet ein Token sofort ab.
Sende es im Authorization-Header. Setze es nie in die URL.

Zugriff und Limits

Jeder Aufruf handelt als die schreibende Person, die verbunden hat, im Rahmen ihres aktuellen Zugriffs und für die Projekte, die für die Verbindung gewählt wurden.
Kein Tool ändert oder löscht den Text der schreibenden Person. Die hinzufügenden Tools erstellen neue Akte, Kapitel, Szenen oder Welteinträge; suggest_edit hinterlässt einen Vorschlag, den die Person in Musael annimmt oder ablehnt.
Jedes Tool wird immer aufgelistet. Ein Tool, das der Tarif oder die Verbindung nicht erlaubt, antwortet mit dem Grund und tut nichts.
Bis zu 300 Aufrufe alle fünf Minuten pro Token. Antworten über 200.000 Zeichen werden gekürzt, mit dem Hinweis, jeweils ein Kapitel oder eine Szene zu lesen.

Tools

15 Tools. Den Text des Buchs lesen und Änderungen vorschlagen gehört zum Tarif Press.

Tool	Was es tut	Tarif	Zugriff
`list_projects`	Die Projekte, die diese Verbindung sehen kann, mit Arbeitsbereich, Rolle der schreibenden Person, Szenen und letzter Änderung. Nutze es zuerst: Jedes andere Tool braucht eine Projekt-ID.	Jeder Tarif	Lesen
`get_profile`	Das verbundene Musael-Konto: eine unveränderliche ID, der Name und die E-Mail-Adresse.	Jeder Tarif	Lesen
`get_outline`	Die Struktur eines Projekts: Bücher, Akte, Kapitel mit Inhaltsangabe, Szenen in Lesereihenfolge mit Status, Erzählperspektive und Wörtern sowie die offenen Aufgaben.	Jeder Tarif	Lesen
`create_project`	Ein neues Projekt aus einer Idee, mit Akten, Kapiteln, leeren Szenen mit Inhaltsangabe und Welteinträgen.	Jeder Tarif	Lesen und hinzufügen
`add_to_plan`	Neue Akte, Kapitel und Szenen in einem bestehenden Projekt.	Jeder Tarif	Lesen und hinzufügen
`add_world_entries`	Neue Figuren, Orte, Gegenstände und Fraktionen. Ein Name, der schon existiert, bleibt unverändert.	Jeder Tarif	Lesen und hinzufügen
`read_scene`	Eine Szene als Markdown, mit Kapitel, Status, Erzählperspektive, Ort und Inhaltsangabe.	Press	Lesen
`read_chapter`	Alle Szenen eines Kapitels, der Reihe nach, als Markdown.	Press	Lesen
`search_project`	Wörter in den Szenen und in der Welt, mit kurzen Ausschnitten.	Press	Lesen
`list_world`	Die Einträge der Welt nach Art, mit anderen Namen, Tags und dem Beginn ihrer Notizen.	Press	Lesen
`get_world_entry`	Ein Welteintrag vollständig: Notizen, Beziehungen, erfasste Fakten und die Szenen, die ihn erwähnen.	Press	Lesen
`get_timeline`	Die Ereignisse der Welt in erzählter Reihenfolge, mit der Szene, die jedes zeigt, und markiert, welche außerhalb der Reihenfolge erzählt werden.	Press	Lesen
`get_style_report`	Der Stilbericht der App zu einer Szene, erstellt nach festen Regeln ohne KI.	Press	Lesen
`get_reader_stats`	Lesende des veröffentlichten Buchs, Kapitel für Kapitel, für Eigentümer und Bearbeitende.	Press	Lesen
`suggest_edit`	Ein Ersetzungsvorschlag für eine Passage oder ein Kommentar dazu. Der Text ändert sich nur, wenn die schreibende Person zustimmt.	Press	Lesen und hinzufügen

Scrolle seitwärts, um die ganze Tabelle zu sehen.

Beispiele

Setze MUSAEL_TOKEN auf ein persönliches Zugriffstoken. Sende nach initialize notifications/initialized und liste dann die Tools auf oder rufe sie auf.

Initialisieren

curl https://app.musael.com/api/mcp?lang=de \
  -H "Authorization: Bearer $MUSAEL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"example","version":"1.0.0"}}}'

Tools auflisten

curl https://app.musael.com/api/mcp?lang=de \
  -H "Authorization: Bearer $MUSAEL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl https://app.musael.com/api/mcp?lang=de \
  -H "Authorization: Bearer $MUSAEL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Ein Tool aufrufen

curl https://app.musael.com/api/mcp?lang=de \
  -H "Authorization: Bearer $MUSAEL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_projects","arguments":{}}}'

Codex

# ~/.codex/config.toml
[mcp_servers.musael]
url = "https://app.musael.com/api/mcp?lang=de"
bearer_token_env_var = "MUSAEL_TOKEN"

Claude Code

claude mcp add --transport http --scope user musael https://app.musael.com/api/mcp?lang=de --header "Authorization: Bearer $MUSAEL_TOKEN"

Ohne Token

HTTP/2 401
www-authenticate: Bearer realm="Musael", resource_metadata="https://app.musael.com/.well-known/oauth-protected-resource/api/mcp"

{"error":"TOKEN_INVALID"}