Musael MCP server

Server

Server URL: https://app.musael.com/api/mcp
Transport: Streamable HTTP, stateless JSON responses. Send JSON-RPC messages with POST; GET and DELETE answer 405.
Server name: musael

Authentication

Every request needs the header Authorization: Bearer <token>. Without a token, or with a revoked, expired or wrong one, the server answers 401 with a WWW-Authenticate header that points to its OAuth metadata.

OAuth sign-in

For ChatGPT, Claude, Cursor, VS Code and other clients that connect by signing in. The client discovers everything from the 401 response, following the MCP authorization specification:

Protected resource metadata (RFC 9728): https://app.musael.com/.well-known/oauth-protected-resource/api/mcp
Authorization server metadata (RFC 8414): https://app.musael.com/.well-known/oauth-authorization-server
Dynamic client registration (RFC 7591): public clients only, without a secret; redirect addresses in HTTPS, HTTP on loopback only, or an app scheme.
Authorization code with PKCE (S256 only). The writer signs in, chooses Read only or Read and add and the projects, then allows or cancels.
Access tokens last one hour; refresh tokens last 90 days and change at every use.
Scopes: read and suggest (shown to the writer as Read and add).

Personal access token

For clients configured by hand, such as Codex, Claude Code or a script. The writer creates the token in Musael under Settings → Connected apps, choosing a name, the projects, the access and when it expires.

Tokens start with sti_ and are shown once; Musael keeps only a hash of them.
An account can have up to 20 active tokens. Revoke turns a token off at once.
Send it in the Authorization header. Never put it in the URL.

Access and limits

Each call acts as the writer who connected, inside the access they have at that moment, on the projects chosen for the connection.
No tool changes or deletes the writer's text. The tools that add create new acts, chapters, scenes or World entries; suggest_edit leaves a proposal that the writer accepts or rejects in Musael.
Every tool is always listed. A tool the plan or the connection does not allow answers with the reason and does nothing.
Up to 300 calls every five minutes per token. Answers longer than 200,000 characters are cut, with a note to read one chapter or scene at a time.

Tools

15 tools. Reading the text of the book and proposing edits come with the Press plan.

Tool	What it does	Plan	Access
`list_projects`	The projects this connection can see, with their workspace, the writer's role, scenes and last change. Use it first: every other tool needs a project id.	Every plan	Read
`get_profile`	The connected Musael account: an id that never changes, the name and the email.	Every plan	Read
`get_outline`	The structure of a project: books, acts, chapters with synopsis, scenes in reading order with status, POV and words, and the open tasks.	Every plan	Read
`create_project`	A new project from an idea, with acts, chapters, empty scenes with synopsis and World entries.	Every plan	Read and add
`add_to_plan`	New acts, chapters and scenes in an existing project.	Every plan	Read and add
`add_world_entries`	New characters, places, objects and factions. A name that already exists is left as it is.	Every plan	Read and add
`read_scene`	One scene as Markdown, with its chapter, status, POV, place and synopsis.	Press	Read
`read_chapter`	Every scene of a chapter, in order, as Markdown.	Press	Read
`search_project`	Words in the scenes and the World, with short excerpts.	Press	Read
`list_world`	The entries of the World by kind, with other names, tags and the start of their notes.	Press	Read
`get_world_entry`	One World entry in full: notes, relationships, recorded facts and the scenes that mention it.	Press	Read
`get_timeline`	The World's events in story order with the scene that shows each one, marking those told out of order.	Press	Read
`get_style_report`	The app's style report on a scene, made by fixed rules without AI.	Press	Read
`get_reader_stats`	Readers of the published book chapter by chapter, for the owner and editors.	Press	Read
`suggest_edit`	A proposed replacement for a passage, or a comment on it. The text changes only if the writer accepts it.	Press	Read and add

Scroll sideways to see the whole table.

Examples

Set MUSAEL_TOKEN to a personal access token. After initialize, send notifications/initialized, then list or call the tools.

Initialize

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

List the tools

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

Call a tool

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

Claude Code

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

Without a 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"}