# Connect an AI app with MCP [#connect-an-ai-app-with-mcp]

Connect your AI app to Lunaris to find a draft or summarize notes across a
workspace. MCP (Model Context Protocol) lets the app work with the resources
you give it permission to access.

To send a single document or use Luna in the workspace, see [Use AI with your work](/customize/connect-ai).

## Connect to Lunaris Cloud [#connect-to-lunaris-cloud]

1. Open the [Lunaris connection page](https://lunaris.app/mcp).
2. Choose the data region where you created your account.
3. Select your AI app, or the generic MCP option.
4. Follow the setup instructions shown for that app.
5. Sign in to Lunaris when asked and review the requested access.

Cloud connections can work with Private and Shared workspaces you can access.
They cannot read Local workspaces stored only on a device.

## Connect to the desktop preview [#connect-to-the-desktop-preview]

1. In the desktop preview, open **Settings → Local Data** and enable **Agent access**.
2. Use the setup details in Lunaris or select **Desktop app** on the [Lunaris connection page](https://lunaris.app/mcp).
3. Connect from your AI app and approve the pairing request in Lunaris.

Keep Lunaris running. This connection can include Local workspaces in the
desktop app, but does not include Local workspaces stored in a separate browser.

## Choose access carefully [#choose-access-carefully]

Start with read-only access if you only need summaries or answers. Editing and
deleting require broader access. Review proposed changes before approving them
in your AI app.

To revoke a desktop connection, open **Settings → Local Data → Agent access**
and choose **Revoke** beside the client. Turning off Agent access revokes all
approved clients.

If cloud workspaces are missing, check the account, data region, and organization
used for the connection.

## Manage cloud connections [#manage-cloud-connections]

Open **Settings → Account → Connected agents** in the connection's data region.
Each connection shows requested permissions, allowed organizations, API audience,
and approval time. **Revoke access** blocks subsequent requests and removes
refresh authorization for that client. Existing in-flight operations may finish.

Agents cannot access unselected organizations, including organizations you join
later. Membership and resource permissions still apply within selected
organizations. Reconnect to change permissions or organization selection.

Connections created before organization consent was introduced must authorize
again. A valid old token alone no longer grants cloud agent access. Existing
client registrations remain usable.

## Remote agents and SSH servers [#remote-agents-and-ssh-servers]

For Hermes on a remote server, use OAuth device authorization. Your browser
stays on Lunaris; Hermes receives tokens by polling the authorization server.
No callback listener or SSH port forwarding is needed.

Configure your selected region's MCP URL in Hermes:

```yaml
mcp_servers:
  lunaris:
    url: "https://YOUR-REGION-API/mcp"
    auth: oauth
    oauth:
      flow: device
      scope: "openid offline_access organization:read workspace:read content:read file:read"
```

On the remote machine, in the same Hermes profile used by your agent:

```sh
hermes mcp login lunaris --flow device
```

Open the printed verification URL on your personal computer. Sign in, confirm
that the code matches your terminal, review permissions, and select allowed
organizations. Approve only requests you started. Return to the terminal;
Lunaris does not redirect your browser to the remote server.

Hermes must support `--flow device`. If the option is unavailable, update
Hermes. Other MCP clients must explicitly implement RFC 8628; browser OAuth
with PKCE remains available for clients using a local callback.

Device requests expire after five minutes. Start login again after expiry or
denial. If the wrong region is selected, reopen the original verification link
and choose the issuing region. Never copy access tokens or session cookies
between machines.