# Use Cydonia's boards from Claude Code outside the app

> Point a Claude Code you run in your own terminal at Cydonia's MCP server, and it reads and works the same boards the app's sessions do.

Cydonia serves its projects' boards, articles and sessions as MCP tools. The sessions it runs are wired to that server already, but any MCP client on the same machine can reach it too. Here is how to connect a Claude Code you run in your own terminal, and what changes when the client is not one Cydonia started.

## Turn the server on

The server lives in the app, so Cydonia has to be running. It opens only while two switches are on:

- `sessions` in **Settings › Features** (⌘,).
- **Serve** in **Settings › MCP**. It is on by default.

With **Serve** on and `sessions` off, **Settings › MCP** says "Sessions is off in Features, so nothing runs to reach it." and shows no address. With both on, it shows the **Address** the server is listening on, with a **Copy** button.

## Find the address

The server speaks Streamable HTTP at `http://127.0.0.1:7457/mcp`, on loopback only. When that port is taken, as by a second Cydonia, it takes the next free one up to 7472. The address in **Settings › MCP** is the one in use; copy it from there if it is not 7457.

## Add it to Claude Code

```sh
claude mcp add --transport http cydonia http://127.0.0.1:7457/mcp
```

There is no token to pass. The server refuses any request carrying an `Origin` header, so a web page in a browser cannot call it. A client that is not a browser sends no `Origin` at all.

## Name the project on every call

A session Cydonia runs is told its project, and its calls may leave the `project` argument out. A client added by hand is not told one. It reaches every project the app has open, and names one per call with `project`: the path of the project's directory.

The project has to be one Cydonia has open. A path to a project that is not open is refused, and the refusal lists the ones that are, as `cydonia does not have /path open — it has …`. Open the project in Cydonia with ⌘O first.

When you know a board's key but not which project holds it, `board_search` takes a key, a card handle or a name, and answers every open project holding a matching board, with the path to pass to the other board tools.

## Read a board

Read-only tools are offered whatever the switches say:

- `board_list` lists a project's boards.
- `board_read` reads one board: its description, then its columns and the cards under them by handle and first line, 50 to a column.
- `board_read_card` reads one card or several by handle: each one's whole text, its column, whether it is busy, the cards it waits on and the cards waiting on it.
- `board_search_cards` finds text in the cards of a project's boards.

## Let it change the board

**Settings › MCP** has two more switches, both off by default:

- **Agents may edit** offers the tools that change a project: `board_add_card`, `board_move_card`, `board_set_card_busy`, `board_set_card_blockers` and the rest.
- **Agents may delete** offers the tools that delete an article, a board or a card. It is read only once **Agents may edit** is on. Archiving needs only **Agents may edit**.

A switched-off tool is left out of the list the client is given rather than refused on the call. The server does not tell a client its list has changed, so after turning a switch on, reconnect Claude Code to the server to see the new tools.

## Busy from outside

`board_set_card_busy` tags a card busy from Claude Code the way it does from a session, and the card shows it on the board. Tagged from a session Cydonia runs, the tag also links that session to the card; Claude Code in your terminal is not a session of the app, so its tags link none.

`board_move_card` answers the cards waiting on each card it moved, so Claude Code learns what a finished card was holding up and can clear their blockers with `board_set_card_blockers`.

See [MCP](https://cydonia.sh/docs/agents/mcp/) for every tool, and [References](https://cydonia.sh/docs/working/references/) for the `DEV-12` and `foo#DEV-12` forms the board tools take.