Lune Research

@retrograde-labs/lune-mcp-server

The official Lune Research MCP server. It lets an AI agent search the full text of papers from top-tier venues, follow citations, and look up curated research-methodology guidance, so its answers can cite each paper by title, authors and venue.

Install

Hosted (recommended). Add this URL to any client that speaks Streamable HTTP:

https://mcp.luneresearch.com

A client that supports MCP authorization signs you in through the browser, so there is no token to paste or rotate. In Claude Code:

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

Then run /mcp inside Claude Code, choose lune, and sign in through the browser tab that opens.

A client without OAuth support sends a Lune access key in the Authorization header instead. Create one on the Credentials page: open API keys and click New key. This request lists the tools, which makes it a quick way to check a key. It reads the key from LUNE_API_KEY, set from your password manager or a file only you can read:

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

The key reaches curl on its input, so it stays out of your shell history and the process list.

Setup notes for specific apps are in the docs: web AI apps such as ChatGPT, Claude and Perplexity, and local AI agents such as Cursor, VS Code and Codex.

Local stdio. For clients that only speak stdio, run the package directly and hand it an access key. It needs Node.js 22 or newer:

{

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

The server reads LUNE_API_KEY from the environment and writes diagnostics to stderr, never stdout, so JSON-RPC framing stays intact.

Tools

Thirteen tools. Most follow a prefix: search_* finds candidates, get_* retrieves something you already have a handle on, and list_* browses. The hosted endpoint also offers request_capability, once Lune has confirmed the user has not opted out of its analytics: an agent calls it to tell Lune about a capability it needed and could not find, and its reply says whether Lune accepted the request. The stdio package does not include it.

Finding papers

Reading them

Working across many at once

Research methodology

Feedback

Prompts

Six prompts, which many MCP clients list as slash commands. Each one hands the agent a brief for a common research task and names the tools to call, so the task takes one command instead of a plan you have to spell out.

Authentication

The hosted endpoint answers discovery (initialize, tools/list, prompts/list and resources/list) without a credential, so an agent can see the tools before anyone signs in. Running a tool takes one credential, as Authorization: Bearer . The stdio package reads an access key from LUNE_API_KEY instead. The credential is one of these:

• An OAuth access token, which an MCP client obtains by signing you in through the browser. Hosted endpoint only.
• A Lune access key (lune_...), created on the Credentials page under API keys. Works on both transports.

An OAuth connection always bills the signed-in person's personal team, drawing on its plan, daily allowance and credits. An access key bills the team it was created in, so a key is how a shared team's plan pays for an agent. How requests are counted is in quotas and billing.

OAuth for connector builders

Most MCP clients run this flow on their own. If you are building a connector, the details follow. auth.md walks through each request with curl.

A tool call without a credential answers 401 with this challenge:

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

The protected-resource document it points to names the authorization server in authorization_servers[0]. That server is https://api.luneresearch.com, the authorization server for MCP connectors. It publishes RFC 8414 metadata at https://api.luneresearch.com/.well-known/oauth-authorization-server and has no OpenID Connect discovery document.

The flow:

1. Register a client. Dynamic client registration is the only way to get a client_id; there are no pre-registered client IDs. Clients are public, so there is no secret and the token endpoint auth method is none. A platform that cannot register on the fly can do it once by hand and keep the 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"]}'

1. Send the person to the authorization endpoint with response_type=code, client_id, redirect_uri, scope, state, code_challenge, code_challenge_method=S256 and resource. PKCE with S256 is required, and so are state and scope.
2. Handle the callback. After the person signs in and approves, Lune redirects to your redirect_uri with code, state and iss=https://api.luneresearch.com (RFC 9207). Check that state is the one you sent and that iss equals the issuer. If the person declines, the redirect carries error=access_denied with the same state and iss.
3. Exchange the code. POST grant_type=authorization_code, code, redirect_uri, client_id, code_verifier and resource to the token endpoint as application/x-www-form-urlencoded.
4. Call the server with Authorization: Bearer . Once the token expires the server answers 401 with error="invalid_token". To refresh, POST grant_type=refresh_token and refresh_token to the token endpoint.

Requirements and limits:

• Request exactly papers:read guidance:read account:read, the scopes the protected-resource document lists. Together they cover every tool.
• Send resource=https://mcp.luneresearch.com on both the authorization request and the token request. Without it the access token is bound to your client_id instead of the server, and requests on protocol version 2026-07-28 fail with 401 invalid_token, which the person sees as a sign-in loop. Older protocol versions still accept such a token, but only for a transition period.
• Redirect URIs must use https, http on 127.0.0.1, [::1] or localhost, or a private-use scheme such as cursor://, and must not contain a fragment. The authorization request must repeat a registered URI exactly, port included.
• An authorization code expires after 10 minutes and works once; a failed exchange uses it up. Access tokens are RS256 JWTs that expire after one hour (expires_in: 3600).
• Every refresh returns a new refresh token. Store it and drop the old one. Each refresh token is valid for 90 days, so a connection in regular use do