Server MCP di Musael

Server

URL del server: https://app.musael.com/api/mcp?lang=it
Trasporto: Streamable HTTP, risposte JSON senza stato. Invia i messaggi JSON-RPC con POST; GET e DELETE rispondono 405.
Nome del server: musael

Autenticazione

Ogni richiesta richiede l'intestazione Authorization: Bearer <token>. Senza token, o con un token revocato, scaduto o errato, il server risponde 401 con un'intestazione WWW-Authenticate che punta ai suoi metadati OAuth.

Accesso OAuth

Per ChatGPT, Claude, Cursor, VS Code e altri client che si collegano accedendo. Il client scopre tutto dalla risposta 401, secondo la specifica di autorizzazione MCP:

Metadati della risorsa protetta (RFC 9728): https://app.musael.com/.well-known/oauth-protected-resource/api/mcp
Metadati del server di autorizzazione (RFC 8414): https://app.musael.com/.well-known/oauth-authorization-server
Registrazione dinamica del client (RFC 7591): solo client pubblici, senza segreto; indirizzi di reindirizzamento in HTTPS, HTTP solo su loopback, oppure uno schema dell'app.
Codice di autorizzazione con PKCE (solo S256). Chi scrive accede, sceglie Sola lettura oppure Lettura e aggiunta e i progetti, poi consente o annulla.
I token di accesso durano un'ora; i token di aggiornamento durano 90 giorni e cambiano a ogni uso.
Ambiti: read e suggest (mostrati a chi scrive come Lettura e aggiunta).

Token di accesso personale

Per i client configurati a mano, come Codex, Claude Code o uno script. Chi scrive crea il token in Musael da Impostazioni → App collegate, scegliendo un nome, i progetti, l'accesso e la scadenza.

I token iniziano con sti_ e vengono mostrati una sola volta; Musael ne conserva solo un hash.
Un account può avere fino a 20 token attivi. Revoca disattiva subito un token.
Invialo nell'intestazione Authorization. Non metterlo mai nell'URL.

Accesso e limiti

Ogni chiamata agisce come la persona che ha collegato l'app, entro l'accesso che ha in quel momento, sui progetti scelti per il collegamento.
Nessuno strumento modifica o elimina il testo di chi scrive. Gli strumenti che aggiungono creano nuovi atti, capitoli, scene o voci del Mondo; suggest_edit lascia una proposta che chi scrive accetta o rifiuta in Musael.
Ogni strumento è sempre elencato. Uno strumento che il piano o il collegamento non consentono risponde con il motivo e non fa nulla.
Fino a 300 chiamate ogni cinque minuti per token. Le risposte oltre i 200.000 caratteri vengono tagliate, con una nota che invita a leggere un capitolo o una scena alla volta.

Strumenti

15 strumenti. La lettura del testo del libro e la proposta di modifiche sono incluse nel piano Press.

Strumento	Cosa fa	Piano	Accesso
`list_projects`	I progetti che questo collegamento può vedere, con il loro spazio di lavoro, il ruolo di chi scrive, le scene e l'ultima modifica. Usalo per primo: ogni altro strumento richiede l'id di un progetto.	Tutti i piani	Lettura
`get_profile`	L'account Musael collegato: un id che non cambia mai, il nome e l'email.	Tutti i piani	Lettura
`get_outline`	La struttura di un progetto: libri, atti, capitoli con sinossi, scene in ordine di lettura con stato, PDV e parole, e le attività aperte.	Tutti i piani	Lettura
`create_project`	Un nuovo progetto a partire da un'idea, con atti, capitoli, scene vuote con sinossi e voci del Mondo.	Tutti i piani	Lettura e aggiunta
`add_to_plan`	Nuovi atti, capitoli e scene in un progetto esistente.	Tutti i piani	Lettura e aggiunta
`add_world_entries`	Nuovi personaggi, luoghi, oggetti e fazioni. Un nome già esistente viene lasciato com'è.	Tutti i piani	Lettura e aggiunta
`read_scene`	Una scena in Markdown, con il suo capitolo, stato, PDV, luogo e sinossi.	Press	Lettura
`read_chapter`	Tutte le scene di un capitolo, in ordine, in Markdown.	Press	Lettura
`search_project`	Parole nelle scene e nel Mondo, con brevi estratti.	Press	Lettura
`list_world`	Le voci del Mondo per tipo, con altri nomi, tag e l'inizio delle loro note.	Press	Lettura
`get_world_entry`	Una voce del Mondo per intero: note, relazioni, fatti registrati e le scene che la citano.	Press	Lettura
`get_timeline`	Gli eventi del Mondo in ordine di storia, con la scena che mostra ciascuno, segnalando quelli raccontati fuori sequenza.	Press	Lettura
`get_style_report`	Il rapporto di stile dell'app su una scena, creato con regole fisse senza IA.	Press	Lettura
`get_reader_stats`	I lettori del libro pubblicato capitolo per capitolo, per chi ne è proprietario e per gli editor.	Press	Lettura
`suggest_edit`	Una proposta di sostituzione per un passaggio, o un commento. Il testo cambia solo se chi scrive accetta.	Press	Lettura e aggiunta

Scorri di lato per vedere l'intera tabella.

Esempi

Imposta MUSAEL_TOKEN su un token di accesso personale. Dopo initialize, invia notifications/initialized, poi elenca o chiama gli strumenti.

Initialize

curl https://app.musael.com/api/mcp?lang=it \
  -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"}}}'

Elenca gli strumenti

curl https://app.musael.com/api/mcp?lang=it \
  -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=it \
  -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"}'

Chiama uno strumento

curl https://app.musael.com/api/mcp?lang=it \
  -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=it"
bearer_token_env_var = "MUSAEL_TOKEN"

Claude Code

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

Senza 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"}