Lune Research permissions
Every OAuth access token and every access key carries an explicit set of
scopes. Scopes decide which tools a credential can call, and each tool checks
its scope when it runs. Any valid credential can also name itself, its team and
its scopes, and list its creator's teams with each team's plan. A team's
credits, daily usage and subscription need account:read, and a credential
reads them only for the team it was issued for.
Scope reference
| Scope | OAuth | Access key | What it grants |
|---|---|---|---|
papers:read | Yes | Yes | The paper tools: search, full text, citations, related papers, extraction, claim checks, evidence |
guidance:read | Yes | Yes | The research guidance tools |
account:read | Yes | Yes | The credits, daily usage and subscription of the team the credential was issued for. Naming its own team and scopes needs no scope. |
subs:rw | If requested | Yes | Which venues the dashboard's Sources page hides from results. No MCP tool uses it. |
keys:rw | If requested | No | Creating access keys in your teams. The Lune command line app uses it. It can't list or revoke keys. |
list_conferences and get_conference_papers need no scope. The full list of
tools and their scopes is under Tools.
What a connector should request
Request exactly the three scopes the MCP server advertises in its
resource metadata:
papers:read guidance:read account:read. They cover every tool. Don't request
subs:rw or keys:rw, even though the authorization server grants them to a
client that asks by name. No MCP tool uses them, and keys:rw would let the app
create access keys that keep working after you disconnect it.
The Lune command line app asks for keys:rw so lune install can create an
access key for a local MCP client after you approve it. A key created that way
can't carry keys:rw itself.
Defaults and changes
A key created in the dashboard carries papers:read, guidance:read,
subs:rw, and account:read. The dashboard asks only for a name. To choose
the scopes or set an expiry, create the key with the command line app:
lune keys create --name ci --scopes papers:read,guidance:readA key's scopes can't change after it's created. To change them, create a new key with the set you want, put it in place of the old one, and revoke the old key.
OAuth clients send a space-separated scope value when they ask for
authorization. Lune drops anything outside the set it supports, shows the rest
on the consent screen, and returns the granted set in the token response. A
request with no scope, or with no scope Lune supports, gets
papers:read guidance:read account:read. A new authorization carries only the
scopes its request names, so a client that needs another scope asks for its full
set again.
When a scope is missing
- OAuth access token. The MCP server answers
403with aWWW-Authenticateheader whoseerrorisinsufficient_scopeand whosescopenames the missing scope. The client should run authorization again with the full set,papers:read guidance:read account:read. - Access key. The tool returns an error that names the missing scope. Create a key that includes it, then retry.
The tool list always shows every tool; scopes decide which calls succeed.
