# 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/mcp` is a different server (browser OAuth, no local files).

## 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/mcp` if you need ChatGPT (no local files). |
| Grok consumer apps                    | Need a public URL. Use Grok CLI stdio on this machine instead.                                                                                                                                                                                      |