Servidor MCP do Musael

Servidor

URL do servidor: https://app.musael.com/api/mcp?lang=pt-BR
Transporte: HTTP em streaming, respostas JSON sem estado. Envie mensagens JSON-RPC com POST; GET e DELETE respondem 405.
Nome do servidor: musael

Autenticação

Toda solicitação precisa do cabeçalho Authorization: Bearer <token>. Sem token, ou com um token revogado, expirado ou errado, o servidor responde 401 com um cabeçalho WWW-Authenticate que aponta para os metadados OAuth dele.

Login por OAuth

Para ChatGPT, Claude, Cursor, VS Code e outros clientes que conectam entrando na conta. O cliente descobre tudo a partir da resposta 401, seguindo a especificação de autorização do MCP:

Metadados do recurso protegido (RFC 9728): https://app.musael.com/.well-known/oauth-protected-resource/api/mcp
Metadados do servidor de autorização (RFC 8414): https://app.musael.com/.well-known/oauth-authorization-server
Registro dinâmico de cliente (RFC 7591): só clientes públicos, sem segredo; endereços de redirecionamento em HTTPS, HTTP somente em loopback, ou um esquema de app.
Código de autorização com PKCE (somente S256). Quem escreve entra, escolhe Somente leitura ou Ler e adicionar e os projetos, e depois permite ou cancela.
Os tokens de acesso duram uma hora; os de renovação duram 90 dias e mudam a cada uso.
Escopos: read e suggest (mostrado a quem escreve como Ler e adicionar).

Token de acesso pessoal

Para clientes configurados à mão, como o Codex, o Claude Code ou um script. Quem escreve cria o token no Musael em Configurações → Apps conectados, escolhendo um nome, os projetos, o acesso e quando expira.

Os tokens começam com sti_ e são mostrados uma vez; o Musael guarda apenas um hash deles.
Uma conta pode ter até 20 tokens ativos. Revogar desativa um token na hora.
Envie-o no cabeçalho Authorization. Nunca o ponha na URL.

Acesso e limites

Cada chamada age como a pessoa que conectou, dentro do acesso que ela tem naquele momento, nos projetos escolhidos para a conexão.
Nenhuma ferramenta altera ou exclui o texto de quem escreve. As ferramentas que adicionam criam novos atos, capítulos, cenas ou entradas do Mundo; suggest_edit deixa uma proposta que a pessoa aceita ou rejeita no Musael.
Toda ferramenta é sempre listada. Uma ferramenta que o plano ou a conexão não permite responde com o motivo e não faz nada.
Até 300 chamadas a cada cinco minutos por token. Respostas com mais de 200.000 caracteres são cortadas, com um aviso para ler um capítulo ou cena de cada vez.

Ferramentas

15 ferramentas. Ler o texto do livro e propor edições vêm com o plano Press.

Ferramenta	O que faz	Plano	Acesso
`list_projects`	Os projetos que esta conexão enxerga, com o espaço de trabalho, o papel da pessoa, as cenas e a última alteração. Use primeiro: toda outra ferramenta precisa de um id de projeto.	Todos os planos	Leitura
`get_profile`	A conta do Musael conectada: um id que nunca muda, o nome e o e-mail.	Todos os planos	Leitura
`get_outline`	A estrutura de um projeto: livros, atos, capítulos com sinopse, cenas na ordem de leitura com status, PDV e palavras, e as tarefas em aberto.	Todos os planos	Leitura
`create_project`	Um novo projeto a partir de uma ideia, com atos, capítulos, cenas vazias com sinopse e entradas do Mundo.	Todos os planos	Ler e adicionar
`add_to_plan`	Novos atos, capítulos e cenas em um projeto existente.	Todos os planos	Ler e adicionar
`add_world_entries`	Novos personagens, lugares, objetos e facções. Um nome que já existe é deixado como está.	Todos os planos	Ler e adicionar
`read_scene`	Uma cena em Markdown, com capítulo, status, PDV, lugar e sinopse.	Press	Leitura
`read_chapter`	Todas as cenas de um capítulo, em ordem, em Markdown.	Press	Leitura
`search_project`	Palavras nas cenas e no Mundo, com trechos curtos.	Press	Leitura
`list_world`	As entradas do Mundo por tipo, com outros nomes, etiquetas e o início das notas.	Press	Leitura
`get_world_entry`	Uma entrada do Mundo completa: notas, relações, fatos registrados e as cenas que a mencionam.	Press	Leitura
`get_timeline`	Os eventos do Mundo na ordem da história, com a cena que mostra cada um, marcando os contados fora de ordem.	Press	Leitura
`get_style_report`	O relatório de estilo do app sobre uma cena, feito por regras fixas, sem IA.	Press	Leitura
`get_reader_stats`	Os leitores do livro publicado, capítulo a capítulo, para quem é dono do projeto e para quem edita.	Press	Leitura
`suggest_edit`	Uma substituição proposta para um trecho, ou um comentário sobre ele. O texto só muda se quem escreve aceitar.	Press	Ler e adicionar

Role para o lado para ver a tabela inteira.

Exemplos

Defina MUSAEL_TOKEN com um token de acesso pessoal. Depois de initialize, envie notifications/initialized e então liste ou chame as ferramentas.

Inicializar

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

Listar as ferramentas

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

Chamar uma ferramenta

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

Claude Code

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

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