# 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](https://luneresearch.com/docs/mcp/remote): 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](https://luneresearch.com/docs/mcp/stdio): 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](https://luneresearch.com/dashboard/install) 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](https://luneresearch.com/docs/mcp/stdio)) | 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](https://luneresearch.com/dashboard/settings/credentials): 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 with `lune_oauth_`. - **Use the authorization code flow with PKCE.** `response_type=code` and `code_challenge_method=S256` are the only options. `state` is 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.com`** on 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 `https` on any host, `http` only on loopback (`127.0.0.1`, `[::1]`, or `localhost`), and private-use schemes such as `cursor://`. Fragments (`#`) aren't allowed. The authorization request has to use one of the registered URIs exactly, except that a registered `http` loopback URI matches on any port (RFC 8252 section 7.3). The callback carries `code`, `iss`, and the `state` you sent. - **Send form-encoded bodies** (`application/x-www-form-urlencoded`) to the token and revocation endpoints, with `client_id` in the body. Lune doesn't read HTTP Basic credentials, and a JSON body gets `422`. - **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](https://luneresearch.com/auth.md). Error codes and fixes are in [Troubleshooting](https://luneresearch.com/docs/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](https://luneresearch.com/docs/concepts/quotas-and-billing) 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](https://luneresearch.com/dashboard/settings/credentials) 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.