Connect AI Assistants

Corkulous includes a Model Context Protocol (MCP) server, so AI assistant apps can work with your boards directly. Once connected, an assistant like Claude Desktop, Claude Code, Codex, or Cursor can list your boards, read their contents, export them, and create new boards from a conversation — research a topic, organize meeting notes, or turn a document into a visual board without leaving the assistant.

Note: AI assistant connections are Mac only and require the Corkulous CLI. See Command Line Tool for CLI installation details.

What Connected Assistants Can Do

Tool	Description
list_boards	List your boards with item counts and dates
get_board	Read a board’s items, positions, and connections
export_board	Export a board to JSON, Markdown, Mermaid, or HTML
get_board_schema	Get the full board JSON format for authoring
create_board_from_json	Create a board from JSON in the conversation
create_board_from_json_file	Create a board from a JSON file on disk
create_board_from_prompt	Generate a board with Corkulous’s own AI pipeline
list_collections	List storage collections (Local, iCloud, Dropbox)

Assistants can read and create boards, but not modify existing ones — edits always happen in Corkulous.

Access, Privacy, and Cost

Read the provider and connected-assistant privacy links, including the assistant you connect. Its policies and your account settings govern retention and data use in that service; Corkulous account deletion does not automatically remove its copies.

Connecting an assistant gives it access to boards exposed by the Corkulous tools. Although the MCP process runs locally, the assistant can send board content to its own model provider and store it in chat history or logs. Review the assistant’s permissions and privacy settings before connecting confidential boards. Corkulous’s in-app board passcode is not file encryption and does not block CLI/MCP access to readable board files. Disconnecting does not erase information already copied elsewhere.

Creating a board from JSON uses the assistant’s prepared content. create_board_from_prompt instead runs the Corkulous CLI’s configured AI pipeline and can make several separately billable provider calls. The assistant’s own subscription or API charges are also separate from Corkulous Credits.

Choosing an Assistant

Use the assistant that fits your workflow: a desktop conversation, a terminal session, or an editor. Corkulous provides setup for Claude Desktop, Claude Code, Codex, and Cursor. Results and available features depend on the assistant version, model, instructions, and account. Connecting through this settings pane configures local clients; it does not add a remote connector to a chat website.

Connect from Corkulous

1. Open Corkulous on your Mac and choose Corkulous > Settings…
2. Select the CLI & Agents tab.
3. In Command Line Tool, click Install… if the CLI is not installed yet.
4. In AI Agents, click Grant Access… and confirm your home folder. Corkulous needs this one-time permission to edit each assistant’s configuration file.
5. Click Connect next to each assistant you want to connect.
6. After the assistant first uses Corkulous, open System Settings > Privacy & Security > Files & Folders and turn on both switches under Corkulous CLI, then restart the assistant. See Allow Board Access.

Each row shows the connection state: Connected (with the configured path), Not connected, Not found on this Mac, or an Update button when a connection points at an old location. Claude Desktop and Cursor need a restart after connecting; Claude Code and Codex pick up the connection in their next session.

Disconnecting removes only the Corkulous entry from the assistant’s configuration — other MCP servers and settings are untouched. Before its first change to any configuration file, Corkulous saves a one-time backup next to it with a .corkulous.bak extension.

Connect from Terminal

The same connections can be managed with the CLI:

# Show which assistants are connected
corkulous agents status

# Connect specific assistants
corkulous agents install --client claude-desktop --client codex

# Connect everything detected on this Mac
corkulous agents install

# Disconnect one assistant
corkulous agents uninstall --client cursor

Useful options:

Option	Description
--client	claude-desktop, claude-code, codex, cursor, or all
--json	Output status as JSON (for status)
--force	Register an assistant even if it was not detected
--server-command	Point configs at a custom corkulous path

The corkulous-boards Skill

Connecting an assistant gives it the tools; the corkulous-boards skill teaches it the workflow — research a topic properly before authoring, build rich boards instead of thin outlines, import large boards reliably, and verify the result. The skill provides structured authoring and verification guidance; results still depend on the assistant and model.

• Claude Code and Codex: The skill is installed automatically when you connect them (from the settings pane or corkulous agents install), and removed when you disconnect.
• Claude Desktop: Skills are managed inside the Claude app. Install it once by hand:

1. Download the skill: corkulous-boards-skill.zip
2. In Claude Desktop, open Settings and select Skills.
3. Click Add, then Upload a skill.
4. Choose the downloaded corkulous-boards-skill.zip.

Note: Skill menus and account availability depend on the assistant version. Installing a skill does not itself connect the Corkulous MCP server to a website. Corkulous automatically manages the bundled skill for Claude Code and Codex; other clients can use the authoring guidance exposed through the MCP tools.

Other MCP Clients

Any app that speaks MCP over stdio can connect. Point it at the installed CLI with the mcp-server argument. For JSON-based clients:

{
  "mcpServers": {
    "corkulous": {
      "command": "/opt/homebrew/bin/corkulous",
      "args": ["mcp-server"]
    }
  }
}

Use command -v corkulous in Terminal to find the installed path, then put that exact path in the client configuration. Apple Silicon Homebrew normally uses /opt/homebrew/bin/corkulous; Intel Homebrew and other installations may use /usr/local/bin/corkulous.

Tips for Better Boards

• Ask for research: “Research the topic first, then create a board” produces richer boards than a bare request.
• Be specific about structure: timelines, comparison zones, and flowcharts all work — say which you want.
• Ask the assistant to read a board back to you: “What’s on my Project Roadmap board?” or “Compare my two planning boards.”
• Ask for an HTML export when you want to preview or share a board outside Corkulous.

Troubleshooting

An assistant shows “Not found on this Mac”

Corkulous looks for each assistant’s app or configuration folder. Install the assistant first, or connect from Terminal with corkulous agents install --client NAME --force.

A connection shows an Update button

The assistant’s configuration points at an old CLI location — this can happen after moving from Intel to Apple Silicon or changing Homebrew setups. Click Update (or re-run corkulous agents install) to point it at the current location.

The assistant says macOS is blocking the Corkulous CLI

macOS needs your one-time approval before the CLI can read your boards. Open System Settings > Privacy & Security > Files & Folders, turn on Corkulous and Data shared by Corkulous CLI Settings and affiliated apps under Corkulous CLI, then restart the assistant. If the message says the launcher is older, click Reinstall… in CLI & Agents first. See Allow Board Access.

The assistant doesn’t see Corkulous tools

Restart the assistant app — Claude Desktop and Cursor load MCP servers at launch. Then confirm the connection with:

corkulous agents status

Boards fail to create from an assistant

Large boards can exceed an assistant’s tool-argument limits. The skill teaches assistants to write board JSON to a file and use create_board_from_json_file, which reduces the amount passed in a single tool call — install the skill for that assistant if you haven’t.