# Connecting Claude Desktop (stdio)

The servers declared in `claude_desktop_config.json` are processes that Claude Desktop
launches itself and talks to through their standard input and output (stdio). PalmaPlan has
served this mode all along, alongside the HTTP + OAuth door of [Claude Code](claude-code.md).
(The remote connectors Claude Desktop adds through its settings would talk to `/mcp` the way
Claude Code does; that path has not been tried with PalmaPlan.)

## The configuration

Open `claude_desktop_config.json` and add:

```json
{
  "mcpServers": {
    "palmaplan": {
      "command": "node",
      "args": ["/path/to/palmaplan/packages/mcp/dist/main.js"],
      "env": {
        "PALMAPLAN_TOKEN": "pp_the-named-token",
        "PALMAPLAN_URL": "http://127.0.0.1:4785"
      }
    }
  }
}
```

*Settings › Connections and agents › Advanced access* (`/settings?onglet=avance`) gives you
this snippet already filled in when you create a named token — in principle only the path to
`main.js` needs adapting.

- **`command` / `args`**: the path to `packages/mcp/dist/main.js` on the machine where
  Claude Desktop runs — the built MCP package's binary, not the API's.
- **`PALMAPLAN_TOKEN`**: a **named token**, created from *Settings › Connections and
  agents › Advanced access*. **Never
  the screen's token** (the `PALMAPLAN_TOKEN` variable the *server* reads at startup) —
  that one isn't attributable to a person, doesn't appear in any attributable log, and
  can't be revoked individually.
- **`PALMAPLAN_URL`**: the address at which this MCP process reaches the API — your
  instance's (`http://127.0.0.1:4785` on your machine), or `https://palmaplan.com` for the
  beta, with a token created **on** the beta. The MCP process always runs on your computer
  (it needs a built copy of the repository, `pnpm build`); it is the one that reaches the
  instance, over HTTPS and through the real-time channel (`wss://`).

## The documented pitfall: which address for `PALMAPLAN_URL`

**`PALMAPLAN_URL` must be the full process's address** (`serveur.js`, what `pnpm start`
launches — the API, the built screen and the embedded view, in the same process),
**never the API alone's** (`packages/api/dist/main.js`).

The reason: for a client that does not render MCP Apps, [`show_schedule`](vue-embarquee.md)
builds the `/embed` view's address from that same origin (or from `PALMAPLAN_PUBLIC_URL`
over HTTP). If `PALMAPLAN_URL` points to an API that does not serve `/embed/:id`, that link
leads nowhere, while every other tool keeps working, since they only talk to the API. The
symptom is therefore misleading: everything seems to work, until the day you open a
schedule's link. Claude Desktop, for its part, shows the native view in the conversation:
it is served by the MCP server itself (the `ui://palmaplan/planning` resource) and reads
everything through it, without going through `/embed`.

## Trying the view in Claude Desktop

The view in the conversation is proven against the repository's test host, **not yet in
Claude Desktop**. Here are the steps to try it. They require quitting and relaunching
Claude Desktop: don't run them during an agent session in progress in Claude Desktop.

1. **PalmaPlan is running**, in a version that contains the native view (0.25.0 or later —
   it arrived with sprint 24, MCP Apps; the version served today is 0.27.0):
   `http://127.0.0.1:4785/api/v1/health` answers, and its `version` says so (use your
   instance's address). The MCP process Claude Desktop launches must come **from the same
   version**: it is the one carrying the view.
2. **A named token**: *Settings › Connections and agents › Advanced access*, "Create a
   token", named "Claude Desktop — view trial", with *Write* checked (read and write). Copy
   the `pp_…` secret: it won't be shown again. Don't paste it into any conversation.
3. **Declare the server**: Claude Desktop › Settings › Developer › Edit config, then add
   the `palmaplan` entry from the configuration above, with that
   token and the full process's address. Node 24 is fine (`"command"` can be its absolute
   path).
4. **Quit Claude Desktop (Cmd+Q) and relaunch it.** Claude Desktop › Settings › Developer
   must show "palmaplan" running. Otherwise, the server's log (`mcp-server-palmaplan.log`, in
   Claude's logs folder) says "serveur MCP PalmaPlan prêt — API : <address>", then
   "connexion établie — N planning(s) accessible(s)". If it says the server refused the
   token, the token is revoked or isn't a named token of this instance.
5. **What to type**, in a new conversation:
   - "Show me the <name> schedule in the conversation." Claude should call
     `show_schedule`.
   - "Make it full screen", then "Show this schedule's kanban", then "and the agenda".
   - Select a bar in the view, then: "Move this bar by a week."
   - "What would happen if I moved <a bar> by a week?" (`what_if`), then "Accept" in the
     view.
6. **What you should see**:
   - the Gantt chart in the conversation, in Claude Desktop's theme colours, inline then
     full screen;
   - a bar moved in the view also moves on the web screen open alongside, and the other
     way round (after a few seconds);
   - Claude moves the selected bar without asking which one;
   - the `what_if` before/after, and "Accept" applying it.
7. **To report**: the Claude Desktop version, what is displayed (a screenshot, without
   secrets), what the frame's console says if developer mode is on, and Claude's answer to
   each request. An empty frame, or duplicated tools, are findings as valuable as a success.
8. **Undo**: remove the `palmaplan` entry from the configuration, relaunch Claude Desktop,
   then revoke the token under *Settings › Connections and agents › Connected
   applications*.

## To confirm

**The real Claude Desktop trial against this configuration has never been run.** Sprint
14 (2026-09-21) prepared a dedicated trial plan and the configuration above, and sprint 24
the steps for the view. But the trial itself (opening Claude Desktop, pasting this block,
checking that the conversation sees the tools and that `show_schedule` displays the view)
needs hands-on access to the machine where Claude Desktop is installed, and hasn't
happened. What is verified, on the other hand: stdio itself (the MCP
protocol over standard input/output) is exercised continuously by the repository's
recettes and by sprint 14's demo video, where a real MCP client over stdio builds a
schedule gesture by gesture while a browser follows the screen through the real-time
channel. What's missing, precisely, is the trial **inside Claude Desktop itself**.