Cydonia
← All posts

Use Cydonia's boards from Claude Code outside the app

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

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 for every tool, and References for the DEV-12 and foo#DEV-12 forms the board tools take.