# Local AI agents

This page covers AI agents installed on your computer: Claude Code, Cursor,
VS Code, Codex, OpenCode, Antigravity, Zed, Devin Desktop, WorkBuddy, OpenClaw,
Hermes Agent, and other MCP clients.

Most of them connect straight to Lune's hosted MCP server at
`https://mcp.luneresearch.com`. A client that can only launch a local process
runs the published stdio package instead. Either way the client needs an access
key, unless it can sign you in through the browser.

## The quick way

Sign in to the dashboard, open the
[Install page](https://luneresearch.com/dashboard/install), and pick your app.
The recipe shows the exact command or config for it, with your access key
filled in.

From a terminal, `lune install` in the [command line app](https://luneresearch.com/docs/cli) sets up
Claude Code, Cursor, VS Code, Codex, or OpenCode for you.

## Set it up by hand

First create an access key. On the
[Credentials page](https://luneresearch.com/dashboard/settings/credentials),
open **API keys** and click **New key**. Copy the key now; the dashboard shows
it once.

### Hosted server

Claude Code accepts this entry as written. Other clients use the same fields
under a different key or in a different format (Codex, for one, uses TOML
with `http_headers`); the Install page shows each client's exact shape.

```json
{
  "mcpServers": {
    "lune": {
      "type": "http",
      "url": "https://mcp.luneresearch.com",
      "headers": { "Authorization": "Bearer lune_your_access_key" }
    }
  }
}
```

If your client supports OAuth for remote servers, you can leave out `headers`.
The client then opens a Lune sign-in in your browser the first time it
connects.

Hermes Agent reads YAML instead. Add Lune under `mcp_servers` in
`~/.hermes/config.yaml` (the Install page has the entry), then run
`/reload-mcp` in your session.

### Local stdio server

Use this for clients that need a local process. It requires Node.js 22 or later
and reads the access key from `LUNE_API_KEY`:

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

To try it from a shell:

```sh
LUNE_API_KEY=lune_your_access_key npx -y @retrograde-labs/lune-mcp-server
```

The first run downloads the package, and later runs use the cached copy. The
stdio server has no browser sign-in, so it always needs a key.

## Common questions

**Do I need to install anything?**
Not for the hosted server. The stdio package installs itself through `npx` the
first time a client starts it.

**Can I use one key on several devices?**
You can, but one key per device lets you revoke only the key on a lost or sold
laptop. The
[Credentials page](https://luneresearch.com/dashboard/settings/credentials)
lists your keys.

**How do I see what the assistant can do?**
Ask it "What Lune tools do you have?" The full list is under
[Tools](https://luneresearch.com/docs/mcp#tools).

## When something goes wrong

- If the assistant says it doesn't have Lune's tools, quit the app fully and
  open it again. Most clients load their tools at startup.
- Many apps show MCP connection logs under **Settings → Tools** or **Settings →
  MCP**. They're the fastest way to see whether Lune connected.
- Lost a key? Revoke it on the Credentials page and create a new one. The old
  key stops working within five minutes.
- Error codes and fixes are in [Troubleshooting](https://luneresearch.com/docs/troubleshooting).