Connect Lune to your AI app
Connect Lune once, then ask your AI agent research questions in plain English. The agent calls Lune's tools to search papers, read full text, trace citations, compare results, check claims, and look up research guidance. You don't need to learn the tool names.
Pick your setup
- Web AI apps: ChatGPT, Claude, Grok, Perplexity, Manus, Muse, Grok Bot, and any app with a custom connector form. Many of them sign you in through the browser.
- Local AI agents: Claude Code, Cursor, VS Code, Codex, OpenCode, Antigravity, Zed, Hermes Agent, and other MCP clients configured with a command or a config file.
The dashboard's Install page has the steps for each app, with your access key filled in where the app needs one.
Connection details
This section is for connector forms, MCP clients, and agents that build a connector themselves. Most apps need only the server URL and discover the rest.
| Setting | Value |
|---|---|
| Server URL | https://mcp.luneresearch.com |
| Older URLs | https://mcp.luneresearch.com/mcp and https://mcp.luneresearch.com/v1/mcp still work |
| Transport | Streamable HTTP, stateless: no sessions. Send JSON-RPC with POST; GET and DELETE get 405 |
| Protocol versions | 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05. initialize is optional |
| Request headers | Content-Type: application/json and Accept: application/json, text/event-stream |
| Credential | Authorization: Bearer followed by an OAuth access token or an access key |
| Local alternative | The stdio package @retrograde-labs/lune-mcp-server (see Local AI agents) |
Current MCP SDKs handle the protocol versions for you. If you write requests by
hand, a POST without an MCP-Protocol-Version header is served as 2025-era
and answered as text/event-stream: one event: message whose data: line is
the JSON-RPC response. A 2026-07-28 request needs the _meta envelope and an
Mcp-Method header, and it's answered as application/json. Sending only the
version header gets 400.
Credentials
The server takes two kinds of credential, both in the Authorization: Bearer
header:
- OAuth access token. The app sends you to Lune to sign in, you approve it, and the app receives a token for your account. Use this whenever the app supports OAuth. There's nothing to copy.
- Access key. A key that starts with
lune_. Create one on the Credentials page: open the API keys tab and click New key. The dashboard shows the key once. Use it when the app can only send a fixed header or asks for an API key.
Authorization server
Lune's authorization server for MCP connectors:
| Item | Value |
|---|---|
| Issuer | https://api.luneresearch.com |
| Authorization endpoint | https://api.luneresearch.com/oauth/authorize |
| Token endpoint | https://api.luneresearch.com/oauth/token |
| Registration endpoint (RFC 7591) | https://api.luneresearch.com/oauth/register |
| Revocation endpoint (RFC 7009) | https://api.luneresearch.com/oauth/revoke |
| JWKS | https://api.luneresearch.com/.well-known/jwks.json |
| Resource metadata (RFC 9728) | https://mcp.luneresearch.com/.well-known/oauth-protected-resource |
| Server metadata (RFC 8414) | https://api.luneresearch.com/.well-known/oauth-authorization-server |
| Scopes | papers:read guidance:read account:read |
| Resource (RFC 8707) | https://mcp.luneresearch.com |
What a client has to do:
- Register to get a client ID. Clients are public. There's no client secret,
and the token endpoint's auth method is
none. The registration endpoint is the only way to get a client ID, which starts withlune_oauth_. - Use the authorization code flow with PKCE.
response_type=codeandcode_challenge_method=S256are the only options.stateis optional but recommended. An authorization code lasts 10 minutes and works once. - Request exactly the three scopes above. Together they cover every tool. A
request with no
scope, or with no scope Lune supports, gets these three. - Send
resource=https://mcp.luneresearch.comon both the authorization request and the token request. If neither carries it, the token's audience is your client ID, and the MCP server rejects such tokens on current protocol versions. - Register exact redirect URIs. Lune accepts
httpson any host,httponly on loopback (127.0.0.1,[::1], orlocalhost), and private-use schemes such ascursor://. Fragments (#) aren't allowed. The authorization request has to use one of the registered URIs exactly, except that a registeredhttploopback URI matches on any port (RFC 8252 section 7.3). The callback carriescode,iss, and thestateyou sent. - Send form-encoded bodies (
application/x-www-form-urlencoded) to the token and revocation endpoints, withclient_idin the body. Lune doesn't read HTTP Basic credentials, and a JSON body gets422. - Rotate refresh tokens. Access tokens are RS256 JWTs that last one hour. Every refresh returns a new refresh token. Store it and discard the old one. A spent refresh token presented again more than 30 seconds later revokes the whole chain. A refresh token expires after 90 days without use.
- Skip OpenID Connect. Lune issues no ID tokens and serves no
/.well-known/openid-configuration.
Every OAuth connection bills your personal team, whichever team the dashboard has selected. To spend a shared team's plan, connect with an access key created in that team.
The whole flow, with requests you can copy, is in auth.md. Error codes and fixes are in Troubleshooting.
Tools
Tool calls count against the daily allowance of the team the credential bills.
Most calls cost one request, the batch tools cost one per item, and
list_conferences is free.
Plans, requests & credits explains the
rules. Each tool checks its scope when it runs.
| Tool | What it does | Scope | Billed per |
|---|---|---|---|
search_papers | Search the corpus with one natural-language query | papers:read | Call |
search_papers_many | Run up to 25 query variants at once and merge the results | papers:read | Query |
search_related_papers | Find papers on the same topic as a given paper | papers:read | Call |
get_paper_fulltext | Read a paper's full text, or only the sections you name | papers:read | Call |
get_paper_citations | List a paper's references, or the indexed papers that cite it | papers:read | Call |
list_conferences | List the venues Lune indexes | None | Free |
get_conference_papers | List a venue's papers, up to 100 per call | None | Call |
extract_from_papers | Build a comparison table from the full text of up to 50 papers | papers:read | Paper |
verify_claims | Check up to 25 claims against the corpus, with a verbatim quote wherever the evidence has one | papers:read | Claim |
gather_evidence | Run up to 25 searches for a task, report what's still missing, and suggest the next searches | papers:read | Search run |
search_research_guidance | Search curated guidance on methods, evaluation, writing, and peer review | guidance:read | Call |
get_research_guidance_doc | Read one guidance document in full | guidance:read | Call |
The hosted server also lists get_more_tools. An agent calls it to tell Lune
about a capability it needed and couldn't find. The call records the request,
returns no research data, and costs nothing. The local stdio server doesn't
offer it.
Prompts
Some apps show these as slash commands. Each one starts a workflow built on the tools above. Plain English works as well. Ask for the same job and the agent picks the tools.
| Prompt | Arguments | What you get |
|---|---|---|
/literature_review | topic (required), venues, since_year | A survey: the main themes, foundational and recent work, and open gaps |
/find_related_work | abstract (required), venues | The prior work to cite, grouped by theme, with a note on how yours differs |
/compare_papers | topic (required: a topic or a list of paper titles), columns | A comparison table read from each paper's full text |
/verify_draft | draft (required) | A verdict for each claim, with a supporting quote where one exists |
/trace_citations | paper (required) | What the paper built on, what built on it, and adjacent work |
/research_methodology | question (required) | Advice on design, ablations, evaluation, rebuttals, or venue choice, with sources |
Every argument is text. venues and columns take comma-separated lists, such
as NeurIPS, ICML or dataset, metric, result.
Manage connections
Connect Lune to as many apps as you like. Connections that bill the same team share its allowance and credits. The Credentials page lists both kinds of credential. The API keys tab shows access keys, and the OAuth clients tab shows the apps you connected by signing in. OAuth connections belong to your personal team, so select it to see them.
