# Lune auth.md

> Authentication contract for Lune MCP connectors and clients. End users should install the Lune connector or plugin in a web chatbot, or add the Lune MCP server to a local agent. Do not call Lune's REST research endpoints directly.

Lune connects an AI app to top-tier research papers and scientific workflow tools. Agents can retrieve abstracts and metadata, trace citations, read full text when available, compare papers, verify claims, and consult curated guidance for literature reviews, evaluation, ablations, and venue selection. Those tools are delivered through Model Context Protocol (MCP). This document explains the OAuth and personal access token flows used by MCP clients.

## At a glance

| Resource                | URL                                                        |
| ----------------------- | ---------------------------------------------------------- |
| Install Lune            | `https://luneresearch.com/dashboard/install`               |
| Remote MCP server       | `https://mcp.luneresearch.com`                             |
| Local stdio MCP package | `@retrograde-labs/lune-mcp-server`                         |
| MCP Registry manifest   | `https://mcp.luneresearch.com/.well-known/mcp/server.json` |
| OAuth issuer            | `https://api.luneresearch.com`                             |
| Dashboard credentials   | `https://luneresearch.com/dashboard/settings/credentials`  |
| Permission reference    | `https://luneresearch.com/docs/concepts/scopes`            |

## Supported connection paths

- **Web chatbots:** install the official Lune connector or plugin. If the app does not list one, add `https://mcp.luneresearch.com` as a custom connector. The app should discover OAuth and ask the user to sign in.
- **Local agents:** add the hosted MCP server or run the published stdio package. The [desktop AI app guide](https://luneresearch.com/docs/mcp/stdio) has exact settings for Codex, Claude Code, Cursor, VS Code, and other clients.
- **Command line setup:** install `@retrograde-labs/lune-cli`, then run `lune install --client <name>`. Use `lune doctor` to check the resulting MCP connection.

The REST service at `api.luneresearch.com` supports these official clients. It is not a supported third-party research integration. In particular, agents should not send research calls to `/api/v1/*`.

## Credentials

MCP clients can authenticate in two ways:

- **OAuth 2.1 with Dynamic Client Registration and PKCE:** best for remote connectors and any client that can open a browser. The user approves access once. The client receives a one-hour access token and a refresh token.
- **Personal Access Token (PAT):** best for a local stdio server, headless client, or CI environment. A person creates the token in the dashboard and chooses its scopes.

Authenticated MCP requests carry the credential as a bearer token:

```http
Authorization: Bearer <token>
```

## OAuth discovery

A compatible client should begin with the MCP endpoint, not hardcoded OAuth URLs. An anonymous MCP request returns `401` with a protected-resource pointer:

```http
WWW-Authenticate: Bearer resource_metadata="https://mcp.luneresearch.com/.well-known/oauth-protected-resource"
```

The pointer follows the MCP address the client called. A request to `https://mcp.luneresearch.com/mcp` points to `https://mcp.luneresearch.com/.well-known/oauth-protected-resource/mcp`. Fetch the named document and use its `authorization_servers[0]` value.

These discovery documents are public:

```bash
curl -sS https://mcp.luneresearch.com/.well-known/oauth-protected-resource
curl -sS https://api.luneresearch.com/.well-known/oauth-authorization-server
curl -sS https://api.luneresearch.com/.well-known/jwks.json
```

Most supported connectors perform the rest of this flow automatically. The manual steps below are for MCP client implementers.

## OAuth client flow

PKCE is required. The only supported method is `S256`. Clients are public and do not receive a client secret.

### 1. Register the MCP client

```bash
curl -sS -X POST https://api.luneresearch.com/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My MCP Client",
    "redirect_uris": ["http://127.0.0.1:13373/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "scope": "papers:read guidance:read subs:rw account:read"
  }'
```

The `201` response includes a `client_id`. Native clients should register a loopback redirect URI and listen on that address for one authorization callback.

### 2. Ask the user to authorize

Generate a high-entropy `code_verifier`, then derive its challenge:

```text
code_challenge = BASE64URL(SHA256(code_verifier))
```

Open the following URL as one line:

```text
https://api.luneresearch.com/oauth/authorize
  ?response_type=code
  &client_id=<client_id>
  &redirect_uri=http://127.0.0.1:13373/callback
  &scope=papers:read%20guidance:read%20subs:rw%20account:read
  &resource=https://mcp.luneresearch.com
  &state=<random_state>
  &code_challenge=<code_challenge>
  &code_challenge_method=S256
```

Confirm the returned `state` before accepting the authorization code.

### 3. Exchange the code

```bash
curl -sS -X POST https://api.luneresearch.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d client_id=<client_id> \
  -d redirect_uri=http://127.0.0.1:13373/callback \
  -d code_verifier=<code_verifier> \
  -d resource=https://mcp.luneresearch.com
```

The response contains an RS256 access token, `expires_in: 3600`, the granted scopes, and a refresh token. Send the access token to the MCP endpoint as `Authorization: Bearer <access_token>`.

### 4. Refresh the connection

```bash
curl -sS -X POST https://api.luneresearch.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=refresh_token \
  -d refresh_token=<refresh_token>
```

The refresh token is valid for 90 days. Each successful refresh slides that window forward. An actively used connector therefore stays connected, while an idle one expires 90 days after its last refresh.

### 5. Revoke the connection

```bash
curl -sS -X POST https://api.luneresearch.com/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d token=<refresh_token>
```

## Personal access token flow

Sign in at `https://luneresearch.com/dashboard/settings/credentials`. Create a token, select its scopes, and copy it when shown. PATs use this format:

```text
lune_xxxxxxxxxxxxxxxxxxxxxxxx
```

The exact pattern is `^lune_[A-Za-z0-9]{24}$`. A PAT carries data scopes only and cannot create, list, or revoke other keys.

Pass a PAT to the local stdio MCP server:

```bash
LUNE_API_KEY=lune_xxxxxxxxxxxxxxxxxxxxxxxx \
  npx -y @retrograde-labs/lune-mcp-server
```

The [Install page](https://luneresearch.com/dashboard/install) provides copy-paste configuration for each supported local agent. Revoke a PAT from the credentials page when a device or local configuration no longer needs it.

## Scopes

Request the least privilege needed by the MCP tools the client enables.

| Scope            | OAuth | PAT | Grants                                                              |
| ---------------- | ----- | --- | ------------------------------------------------------------------- |
| `papers:read`    | Yes   | Yes | Search papers and read full text, citations, and related work.      |
| `guidance:read`  | Yes   | Yes | Search curated scientific workflow guidance.                        |
| `subs:rw`        | Yes   | Yes | Choose which conferences appear in results. The name is historical. |
| `account:read`   | Yes   | Yes | Read account identity and usage.                                    |
| `keys:rw`        | Yes   | No  | Create one PAT after consent. OAuth cannot list or revoke PATs.     |
| `workspace:read` | No    | Yes | Search documents in an active Lune Workspace session.               |

The full compatibility rules and `403` error shape are at `https://luneresearch.com/docs/concepts/scopes`. Unsupported PAT scopes are rejected instead of silently removed.

## MCP authentication failures

| Result | Meaning                            | Client action                                                                 |
| ------ | ---------------------------------- | ----------------------------------------------------------------------------- |
| `401`  | Missing, invalid, or expired token | Follow `WWW-Authenticate`, refresh or restart OAuth, then retry the MCP call. |
| `403`  | Missing scope                      | Ask the user to reconnect with the scope named by the tool error.             |
| `402`  | Daily allowance and credits spent  | Stop and show the billing action returned by Lune.                            |
| `429`  | Short burst limit                  | Wait for the retry delay, then retry the same MCP tool call once.             |

The underlying API's version, deprecation, rate-limit, and typed error contract is published at `https://luneresearch.com/docs/api` for inspection. It is not a guide for direct REST integration.

## OAuth endpoint reference

| Method | Endpoint                                  | Purpose                                                 |
| ------ | ----------------------------------------- | ------------------------------------------------------- |
| `POST` | `/oauth/register`                         | Register an MCP client with Dynamic Client Registration |
| `GET`  | `/oauth/authorize`                        | Start the authorization-code flow with PKCE             |
| `POST` | `/oauth/token`                            | Exchange a code or refresh an access token              |
| `POST` | `/oauth/revoke`                           | Revoke a refresh token                                  |
| `GET`  | `/.well-known/oauth-protected-resource`   | MCP resource metadata                                   |
| `GET`  | `/.well-known/oauth-authorization-server` | Authorization-server metadata                           |
| `GET`  | `/.well-known/jwks.json`                  | Access-token signing keys                               |

Questions or trouble: support@luneresearch.com