Lune

Conhecimento e ferramentas de pesquisa científica

Documentação

@retrograde-labs/lune-mcp-server

O servidor MCP oficial da Lune Research. Ele permite que um agente de IA pesquise o texto completo de artigos de conferências de alto nível, siga citações e consulte orientações selecionadas de metodologia de pesquisa, para que suas respostas possam citar o título, os autores e a conferência de um artigo, em vez de depender da memória.

Instalação

Hospedado (recomendado). Adicione esta URL a qualquer cliente que suporte Streamable HTTP:

https://mcp.luneresearch.com

Um cliente que suporte autorização MCP faz seu login pelo navegador, então não há token para colar ou rotacionar. No Claude Code:

claude mcp add --transport http --scope user lune https://mcp.luneresearch.com

Em seguida, execute /mcp dentro do Claude Code, escolha lune e faça login pela aba do navegador que abrir.

Um cliente sem suporte a OAuth envia uma chave de acesso Lune no cabeçalho Authorization. Crie uma na página de Credenciais: abra API keys e clique em New key. Esta solicitação lista as ferramentas, o que a torna uma forma rápida de verificar uma chave. Ela lê a chave de LUNE_API_KEY, definida a partir do seu gerenciador de senhas ou de um arquivo que só você pode ler:

printf 'Authorization: Bearer %s\n' "$LUNE_API_KEY" |
  curl https://mcp.luneresearch.com \
    -H @- \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A chave chega ao curl pela entrada padrão, então ela fica fora do histórico do shell e da lista de processos.

Notas de configuração para aplicativos específicos estão na documentação: aplicativos de IA web como ChatGPT, Claude e Perplexity, e agentes de IA locais como Cursor, VS Code e Codex.

stdio local. Para clientes que só falam stdio, execute o pacote diretamente e forneça uma chave de acesso. É necessário Node.js 22 ou mais recente:

{
  "mcpServers": {
    "lune": {
      "command": "npx",
      "args": ["-y", "@retrograde-labs/lune-mcp-server"],
      "env": { "LUNE_API_KEY": "lune_your_access_key" }
    }
  }
}

O servidor lê LUNE_API_KEY do ambiente e escreve diagnósticos em stderr, nunca em stdout, para que o enquadramento JSON-RPC permaneça intacto.

Ferramentas

Doze ferramentas. A maioria segue um prefixo: search_* encontra candidatos, get_* recupera algo que você já tem em mãos, e list_* navega. O endpoint hospedado também oferece get_more_tools, que um agente chama para informar à Lune sobre uma capacidade que precisou e não encontrou. O pacote stdio não a inclui.

Encontrando artigos

Ferramenta	O que faz
`search_papers`	Busca híbrida vetorial + BM25 no corpus
`search_papers_many`	Muitas variantes de consulta em uma chamada, mescladas por fusão de classificação recíproca
`search_related_papers`	Os vizinhos mais próximos de um artigo que você já tem
`list_conferences`	Conferências indexadas, opcionalmente filtradas por categoria
`get_conference_papers`	Artigos de uma conferência, paginados

Lendo-os

Ferramenta	O que faz
`get_paper_fulltext`	Texto completo analisado, como markdown ou JSON
`get_paper_citations`	O grafo de citações, em qualquer direção

Trabalhando com muitos de uma vez

Ferramenta	O que faz
`extract_from_papers`	Extrair os mesmos campos estruturados de um conjunto de artigos
`verify_claims`	Verificar cada afirmação contra o corpus, com uma citação literal quando existir
`gather_evidence`	Avaliar se a evidência já é suficiente e nomear o que está faltando

Metodologia de pesquisa

Ferramenta	O que faz
`search_research_guidance`	O corpus selecionado de metodologia e reprodutibilidade
`get_research_guidance_doc`	O texto completo de um documento de orientação

Prompts

Seis prompts, que muitos clientes MCP listam como comandos de barra. Cada um entrega ao agente um briefing para uma tarefa comum de pesquisa e nomeia as ferramentas a chamar, para que a tarefa leve um comando em vez de um plano que você precise detalhar.

Prompt	O que faz	Argumentos
`/literature_review`	Levantar um tópico: os principais temas, trabalhos fundamentais e recentes, e lacunas em aberto	`topic` (+ `venues`, `since_year`)
`/find_related_work`	Ler seu resumo e, em seguida, encontrar o trabalho anterior para citar e do qual se diferenciar	`abstract` (+ `venues`)
`/compare_papers`	Construir uma tabela de comparação entre artigos, lida a partir do texto completo	`topic` (+ `columns`)
`/verify_draft`	Verificar cada afirmação em um rascunho, com uma citação literal quando existir	`draft`
`/trace_citations`	Rastrear a linhagem de um artigo: no que ele se baseia, o que se baseia nele	`paper`
`/research_methodology`	Orientação fundamentada sobre design de experimentos, ablações, avaliação, réplicas, conferências	`question`

Autenticação

O endpoint hospedado aceita uma credencial em cada solicitação, como Authorization: Bearer <credential>. O pacote stdio lê uma chave de acesso de LUNE_API_KEY. A credencial é uma destas:

Um token de acesso OAuth, que um cliente MCP obtém ao fazer seu login pelo navegador. Somente endpoint hospedado.
Uma chave de acesso Lune (lune_...), criada na página de Credenciais em API keys. Funciona em ambos os transportes.

Uma conexão OAuth sempre cobra o time pessoal da pessoa conectada, usando seu plano, cota diária e créditos. Uma chave de acesso cobra o time em que foi criada, então uma chave é como o plano de um time compartilhado paga por um agente. Como as solicitações são contabilizadas está em cotas e cobrança.

OAuth para construtores de conectores

A maioria dos clientes MCP executa esse fluxo por conta própria. Se você está construindo um conector, os detalhes vêm a seguir. auth.md percorre cada solicitação com curl.

Um POST https://mcp.luneresearch.com não autenticado responde a 401 com este desafio:

WWW-Authenticate: Bearer resource_metadata="https://mcp.luneresearch.com/.well-known/oauth-protected-resource", scope="papers:read guidance:read account:read"

O documento de recurso protegido para o qual ele aponta nomeia o servidor de autorização em authorization_servers[0]. Esse servidor é https://api.luneresearch.com, o servidor de autorização para conectores MCP. Ele publica metadados RFC 8414 em https://api.luneresearch.com/.well-known/oauth-authorization-server e não possui documento de descoberta OpenID Connect.

Endpoint	URL
Emissor	`https://api.luneresearch.com`
Autorização	`https://api.luneresearch.com/oauth/authorize`
Token	`https://api.luneresearch.com/oauth/token`
Registro de cliente (RFC 7591)	`https://api.luneresearch.com/oauth/register`
Revogação (RFC 7009)	`https://api.luneresearch.com/oauth/revoke`
JWKS	`https://api.luneresearch.com/.well-known/jwks.json`
Metadados do servidor de autorização	`https://api.luneresearch.com/.well-known/oauth-authorization-server`
Metadados do recurso protegido	`https://mcp.luneresearch.com/.well-known/oauth-protected-resource`

O fluxo:

Registre um cliente. O registro dinâmico de clientes é a única forma de obter um client_id; não há IDs de cliente pré-registrados. Os clientes são públicos, então não há segredo e o método de autenticação do endpoint de token é none. Uma plataforma que não consegue registrar em tempo real pode fazê-lo uma vez manualmente e guardar o client_id:
```
curl -X POST https://api.luneresearch.com/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My connector", "redirect_uris": ["https://example.com/oauth/callback"]}'
```
Envie a pessoa para o endpoint de autorização com response_type=code, client_id, redirect_uri, scope, state, code_challenge, code_challenge_method=S256 e resource. PKCE com S256 é obrigatório, assim como state e scope.
Trate o callback. Após a pessoa entrar e aprovar, a Lune redireciona para seu redirect_uri com code, state e iss=https://api.luneresearch.com (RFC 9207). Verifique se state é o mesmo que você enviou e se iss é igual ao emissor. Se a pessoa recusar, o redirecionamento carrega error=access_denied com o mesmo state e iss.
Troque o código. POST grant_type=authorization_code, code, redirect_uri, client_id, code_verifier e resource para o endpoint de token como application/x-www-form-urlencoded.
Chame o servidor com Authorization: Bearer <access_token>. Quando o token expirar, o servidor responde a 401 com error="invalid_token". Para atualizar, POST grant_type=refresh_token e refresh_token para o endpoint de token.

Requisitos e limites:

Solicite exatamente papers:read guidance:read account:read, os escopos que o documento de recurso protegido lista. Juntos, eles cobrem todas as ferramentas.
Envie resource=https://mcp.luneresearch.com tanto na solicitação de autorização quanto na solicitação de token. Sem ele, o token de acesso é vinculado ao seu client_id em vez do servidor, e solicitações na versão de protocolo 2026-07-28 falham com 401 invalid_token, o que a pessoa vê como um loop de login. Versões mais antigas do protocolo ainda aceitam esse token, mas apenas por um período de transição.
URIs de redirecionamento devem usar https, http em 127.0.0.1, [::1] ou localhost, ou um esquema de uso privado como cursor://, e não devem conter fragmento. A solicitação de autorização deve repetir uma URI registrada exatamente, incluindo a porta.
Um código de autorização expira após 10 minutos e funciona uma única vez; uma troca com falha o consome. Tokens de acesso são JWTs RS256 que expiram após uma hora (expires_in: 3600).
Cada atualização retorna um novo token de atualização. Armazene-o e descarte o antigo. Cada token de atualização é válido por 90 dias, então uma conexão em uso regular não expira. Apresentar um token de atualização mais de 30 segundos após ele ter sido substituído revoga todos os tokens de atualização nessa cadeia, e a pessoa precisa se conectar novamente. Tokens de acesso já emitidos continuam funcionando até expirarem.
Para desconectar, POST token=<refresh_token> (codificado em formulário) para o endpoint de revogação.

Escopos

papers:read cobre o corpus de artigos, texto completo e citações, guidance:read cobre o corpus de orientação de pesquisa, e account:read lê sua identidade e uso.

Uma credencial que não tenha o escopo que uma ferramenta precisa falha de forma diferente dependendo do seu tipo. Um token OAuth recebe HTTP 403 com um desafio que nomeia apenas o escopo ausente, para que o cliente possa pedir que a pessoa o aprove:

WWW-Authenticate: Bearer error="insufficient_scope", error_description="The papers:read scope is required for this request.", resource_metadata="https://mcp.luneresearch.com/.well-known/oauth-protected-resource", scope="papers:read"

Uma chave de acesso recebe um erro de ferramenta que nomeia o escopo ausente e diz ao agente para você criar uma chave que o inclua.

Revogando acesso

Revogue chaves de acesso em API keys e aplicativos conectados em OAuth clients na página de Credenciais. Conexões OAuth estão listadas no seu time pessoal, então selecione-o primeiro. Uma chave de acesso revogada para de funcionar em até cinco minutos. Revogar um aplicativo cancela seus tokens de atualização imediatamente, mas o token de acesso que ele já possui continua funcionando até expirar, no máximo uma hora depois.

Transportes

Transporte	Onde	Versões do protocolo MCP
Streamable HTTP	`https://mcp.luneresearch.com`	2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07
stdio	`npx -y @retrograde-labs/lune-mcp-server`	2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07
Sobre o endpoint hospedado:

/mcp e /v1/mcp também respondem, para instalações mais antigas. A descoberta segue o caminho, então um cliente em /mcp é direcionado para https://mcp.luneresearch.com/.well-known/oauth-protected-resource/mcp. Um token vinculado a qualquer uma das três URLs funciona em todas as três.
As requisições são sem estado. Cada uma carrega sua própria credencial e não há ID de sessão, então um cliente que ficou ocioso por horas continua funcionando sem reinicializar.
O tráfego MCP é somente POST. GET e DELETE retornam 405, então não há stream SSE para abrir, e o servidor não envia notificações próprias. Um navegador que abre a URL simples é redirecionado para a documentação.
Envie Accept: application/json, text/event-stream. Em versões de protocolo mais antigas, uma requisição que omita qualquer um dos tipos recebe 406.
Uma requisição com cabeçalho Origin recebe 403 a menos que essa origem esteja na lista de permissões do servidor, então conecte-se a partir de um servidor ou de um cliente nativo, em vez de a partir de uma página web.
Lotes JSON-RPC, que apenas versões de protocolo mais antigas usam, podem conter até 50 mensagens. Um corpo de requisição pode ter até 1 MB.
O manifesto do Registry é servido em https://mcp.luneresearch.com/.well-known/mcp/server.json.

Suporte

Relatórios de bugs e solicitações de recursos vão para o rastreador de problemas. Para dúvidas sobre contas, envie um e-mail para support@luneresearch.com. Para relatar um problema de segurança, siga SECURITY.md.

Licença

MIT