# Desktop MCP
Source: https://docs.aden.space/docs/help/apps-integrations/desktop-mcp

Local MCP for Claude Code, Cursor, Codex, and Grok CLI. Desktop must be open. Uses the local session, not pasted API keys.
{/* Generated by `bun docs:publish` from docs/features/desktop-mcp.md: edit the spec, not this file. */}

## What it is [#what-it-is]

A local MCP so your existing Claude Code, Cursor, Codex, or Grok CLI app can read Aden tracks and files through the Aden desktop app on this machine. Aden Desktop does not embed those models. You do not paste an API key.

Keep Desktop open and signed in. If it is quit, tools tell you to open it again.

Hosted MCP at `https://mcp.aden.space` is a different server (browser OAuth, no local files).

## Let your AI set it up [#let-your-ai-set-it-up]

The top of the MCP DAW screen, Connect tab, has one button per assistant: Claude, ChatGPT, Gemini and Grok, plus **Copy prompt** for coding agents. Each button copies a setup prompt and opens that assistant. Claude, ChatGPT and Grok start a new chat with the prompt already filled in. On Gemini, and on Windows (links over 2083 characters get cut), you paste it.

The prompt tells your AI to:

* install the hosted server as `aden-cloud` and, when it runs on your computer, the local one as `aden`
* skip anything already installed
* use the exact commands for Claude Code, Codex, Gemini CLI, Grok CLI, Cursor, Windsurf and VS Code, and give step-by-step instructions for the Claude, ChatGPT and other chat apps
* have you sign in on aden.space in the browser, never in the chat
* use the team you have open in Desktop, then prove the setup works by listing your teams and recent tracks

## Stdio (preferred) [#stdio-preferred]

Same launch command everywhere: `npx -y @aden/desktop-mcp`.

| Client      | Transport | Command or config                                                                                      | Desktop must be running                                    |
| ----------- | --------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| Claude Code | stdio     | `claude mcp add aden -- npx -y @aden/desktop-mcp`                                                      | Yes, when you call tools. Install can be saved while quit. |
| Cursor      | stdio     | Settings → MCP, or `~/.cursor/mcp.json` / `.cursor/mcp.json` with the JSON below                       | Yes, when you call tools                                   |
| Codex CLI   | stdio     | `codex mcp add aden -- npx -y @aden/desktop-mcp` writes `[mcp_servers.aden]` in `~/.codex/config.toml` | Yes, when you call tools                                   |
| Grok CLI    | stdio     | `grok mcp add aden -- npx -y @aden/desktop-mcp` writes `~/.grok/config.toml`                           | Yes, when you call tools                                   |
| Windsurf    | stdio     | Same JSON as Cursor, in `~/.codeium/windsurf/mcp_config.json`                                          | Yes, when you call tools                                   |

Cursor / Windsurf JSON:

```json
{
  "mcpServers": {
    "aden": {
      "command": "npx",
      "args": ["-y", "@aden/desktop-mcp"]
    }
  }
}
```

OpenCode uses a different JSON shape (`mcp` + `command` as one array), so the Cursor JSON does not paste unchanged. Skip it here.

## HTTP localhost [#http-localhost]

Use this when the client cannot spawn stdio. URL: `http://127.0.0.1:48731/mcp`. Desktop must be running. Auth is the pairing token from Desktop (copy the HTTP command in the AI panel). Do not paste that token into a chat.

| Client      | Transport | Command or config                                                                                                                                                                                                                       | Desktop must be running |
| ----------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| Claude Code | HTTP      | Copy **Claude Code HTTP** from Desktop. Shape: `claude mcp add --transport http aden-desktop http://127.0.0.1:48731/mcp --header "Authorization: Bearer <token>"`                                                                       | Yes                     |
| Codex CLI   | HTTP      | `codex mcp add aden-desktop --url http://127.0.0.1:48731/mcp --bearer-token-env-var ADEN_DESKTOP_MCP_TOKEN` then set `ADEN_DESKTOP_MCP_TOKEN` from Desktop. Copy **Codex HTTP** from the AI panel if you want the env prefix filled in. | Yes                     |
| Cursor      | HTTP      | `url` plus `headers.Authorization` Bearer, token from env `${env:ADEN_DESKTOP_MCP_TOKEN}`                                                                                                                                               | Yes                     |
| Grok CLI    | HTTP      | `grok mcp add --transport http aden-desktop http://127.0.0.1:48731/mcp --header "Authorization: Bearer <token>"`                                                                                                                        | Yes                     |
| Windsurf    | HTTP      | Same token header, but the URL field is `serverUrl`, not `url`                                                                                                                                                                          | Yes                     |

HTTP `/mcp` also includes DAW tools. Stdio only exposes catalog tools.

## Not supported on localhost [#not-supported-on-localhost]

| Client                                | Why                                                                                                                                                                                                                                             |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ChatGPT (developer mode / connectors) | ChatGPT only talks to a remote HTTPS MCP. `127.0.0.1` is not reachable from chatgpt.com. A public tunnel or OpenAI Secure MCP Tunnel would expose this machine. Skip. Use hosted `https://mcp.aden.space` if you need ChatGPT (no local files). |
| Grok consumer apps                    | Need a public URL. Use Grok CLI stdio on this machine instead.                                                                                                                                                                                  |