Server
- Server-URL
https://app.musael.com/api/mcp?lang=nl- Transport
- Streamable HTTP, stateloze JSON-antwoorden. Stuur JSON-RPC-berichten met POST; GET en DELETE antwoorden met 405.
- Servernaam
musael
Authenticatie
Elk verzoek heeft de header Authorization: Bearer <token> nodig. Zonder token, of met een ingetrokken, verlopen of onjuist token, antwoordt de server met 401 en een WWW-Authenticate-header die naar de OAuth-metadata verwijst.
OAuth-login
Voor ChatGPT, Claude, Cursor, VS Code en andere clients die verbinden via inloggen. De client ontdekt alles uit het 401-antwoord, volgens de MCP-autorisatiespecificatie:
- Metadata van de beschermde resource (RFC 9728):
https://app.musael.com/.well-known/oauth-protected-resource/api/mcp - Metadata van de autorisatieserver (RFC 8414):
https://app.musael.com/.well-known/oauth-authorization-server - Dynamische clientregistratie (RFC 7591): alleen publieke clients, zonder geheim; redirect-adressen in HTTPS, HTTP alleen op loopback, of een app-schema.
- Autorisatiecode met PKCE (alleen S256). De schrijver logt in, kiest Alleen lezen of Lezen en toevoegen en de projecten, en staat het dan toe of annuleert.
- Toegangstokens gelden een uur; vernieuwingstokens gelden 90 dagen en veranderen bij elk gebruik.
- Scopes: read en suggest (voor de schrijver weergegeven als Lezen en toevoegen).
Persoonlijk toegangstoken
Voor clients die je met de hand instelt, zoals Codex, Claude Code of een script. De schrijver maakt het token in Musael aan onder Instellingen → Verbonden apps, en kiest een naam, de projecten, de toegang en wanneer het verloopt.
- Tokens beginnen met sti_ en worden één keer getoond; Musael bewaart er alleen een hash van.
- Een account kan tot 20 actieve tokens hebben. Intrekken schakelt een token meteen uit.
- Stuur het mee in de Authorization-header. Zet het nooit in de URL.
Toegang en limieten
- Elke aanroep handelt namens de schrijver die heeft verbonden, binnen de toegang die de schrijver op dat moment heeft, op de projecten die voor de verbinding zijn gekozen.
- Geen enkele tool wijzigt of verwijdert de tekst van de schrijver. De tools die toevoegen, maken nieuwe akten, hoofdstukken, scènes of Wereld-vermeldingen; suggest_edit laat een voorstel achter dat de schrijver in Musael accepteert of afwijst.
- Elke tool staat altijd in de lijst. Een tool die het abonnement of de verbinding niet toestaat, antwoordt met de reden en doet niets.
- Maximaal 300 aanroepen per vijf minuten per token. Antwoorden van meer dan 200.000 tekens worden afgekapt, met de aanwijzing om één hoofdstuk of scène tegelijk te lezen.
Tools
15 tools. De tekst van het boek lezen en bewerkingen voorstellen horen bij het abonnement Press.
| Tool | Wat het doet | Abonnement | Toegang |
|---|---|---|---|
list_projects | De projecten die deze verbinding kan zien, met hun werkruimte, de rol van de schrijver, scènes en laatste wijziging. Gebruik dit eerst: elke andere tool heeft een project-id nodig. | Elk abonnement | Lezen |
get_profile | Het verbonden Musael-account: een id die nooit verandert, de naam en het e-mailadres. | Elk abonnement | Lezen |
get_outline | De structuur van een project: boeken, akten, hoofdstukken met synopsis, scènes in leesvolgorde met status, perspectief en woorden, en de openstaande taken. | Elk abonnement | Lezen |
create_project | Een nieuw project vanuit een idee, met akten, hoofdstukken, lege scènes met synopsis en Wereld-vermeldingen. | Elk abonnement | Lezen en toevoegen |
add_to_plan | Nieuwe akten, hoofdstukken en scènes in een bestaand project. | Elk abonnement | Lezen en toevoegen |
add_world_entries | Nieuwe personages, plaatsen, voorwerpen en facties. Een naam die al bestaat, blijft ongemoeid. | Elk abonnement | Lezen en toevoegen |
read_scene | Eén scène als Markdown, met hoofdstuk, status, perspectief, plaats en synopsis. | Press | Lezen |
read_chapter | Alle scènes van een hoofdstuk, op volgorde, als Markdown. | Press | Lezen |
search_project | Woorden in de scènes en de Wereld, met korte fragmenten. | Press | Lezen |
list_world | De vermeldingen van de Wereld per soort, met andere namen, labels en het begin van hun notities. | Press | Lezen |
get_world_entry | Eén Wereld-vermelding volledig: notities, relaties, vastgelegde feiten en de scènes waarin ze wordt genoemd. | Press | Lezen |
get_timeline | De gebeurtenissen van de Wereld in verhaalvolgorde met de scène die elk toont, met markering van wat niet chronologisch wordt verteld. | Press | Lezen |
get_style_report | Het stijlrapport van de app over een scène, gemaakt met vaste regels, zonder AI. | Press | Lezen |
get_reader_stats | Lezers van het gepubliceerde boek per hoofdstuk, voor de eigenaar en redacteuren. | Press | Lezen |
suggest_edit | Een voorgestelde vervanging voor een passage, of een opmerking erbij. De tekst verandert alleen als de schrijver het accepteert. | Press | Lezen en toevoegen |
Scrol opzij om de hele tabel te zien.
Voorbeelden
Zet MUSAEL_TOKEN op een persoonlijk toegangstoken. Stuur na initialize notifications/initialized en toon of roep daarna de tools aan.
Initialiseren
curl https://app.musael.com/api/mcp?lang=nl \
-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"}}}'De tools opsommen
curl https://app.musael.com/api/mcp?lang=nl \
-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=nl \
-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"}'Een tool aanroepen
curl https://app.musael.com/api/mcp?lang=nl \
-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=nl"
bearer_token_env_var = "MUSAEL_TOKEN"Claude Code
claude mcp add --transport http --scope user musael https://app.musael.com/api/mcp?lang=nl --header "Authorization: Bearer $MUSAEL_TOKEN"Zonder 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"}