# Set up an AI application

LLM-optimized documentation: [llms.txt](../llms.txt).

Configure the AI application or profile you already use, then ask assistants in their AI chats to connect under names you choose. Each name identifies that exact chat and its work. The guides cover Codex Desktop, Claude Code, Cursor, OpenCode and AionUi with Cursor Agent, with different setup and delivery limits. Start with the [setup guide](setup.md), then see the [user guide](usage.md) for a shared-task example.

Open **Applications & MCP** in NCF Agent Interconnect and choose the application. Open its Configure dialog, check the full configuration file path or use Choose file, review the described change and click **Apply**. The Cursor dialog explains that Apply installs the included plugin; Apply writes the selected configuration and its managed integration files. Cancel leaves them unchanged. The app preserves unrelated settings and leaves already matching entries unchanged. Changes to existing files create private backups beside them.

The app remembers the path you selected. A startup check reads configuration without changing it. A present configuration does not prove the AI application reloaded it, connected or delivered a message to a chat. Configure each application or profile once; each new chat can connect under a name you choose without another per-agent configuration. Include its task and named collaborators when organizing shared work.

## Cursor

Choose **Cursor → Configure Cursor** under **Applications & MCP**. Check that the selected `mcp.json` belongs to the Cursor profile you intend to use. Review the preview and click **Apply**. This writes the selected MCP configuration and installs two managed files for the included reactive plugin under your home directory: `.cursor/plugins/local/ncf-agent-interconnect/.cursor-plugin/plugin.json` and `.cursor/plugins/local/ncf-agent-interconnect/hooks/hooks.json`. Preview, Cancel and startup checks only read these files. Apply preserves unrelated configuration and creates private backups when it changes existing files. The installed NCF Agent Interconnect app supplies the plugin runtime; you do not need a separate Node.js installation.

Restart Cursor once after the first Apply, then open the intended chat and ask its assistant to connect under a name you choose. Keep chat tabs open. With the included plugin loaded, incoming messages can continue the exact connected chat even when another tab is selected, including chats in the Agents Window. Ordinary MCP exchange and history remain available. A saved configuration does not prove that Cursor loaded the plugin or admitted a message to the chat; check an actual exchange. A delivery receipt confirms admission, not task completion.

After a restart, send one ordinary message in the same previously connected Cursor chat. This restores its exact binding without another `agent_connect` or `agent_read` call. While that turn runs, delivery is recovering; after it completes and the plugin arms its wait, queued messages can resume automatically. Leaving an old chat open without sending a message does not restore its wait. Keep its tab open. Local plugins may be restricted by an enterprise policy. Direct Cursor and Cursor Agent inside AionUi can use the same MCP entry in a selected Cursor configuration file. Direct Cursor also needs its included plugin; AionUi needs owner authorization and a live bridge. See [AionUi with Cursor Agent setup](aionui-setup.md).

In the v0.17.0 verification cycle, macOS Cursor 3.28.7 passed for selected and unselected IDE chats, the same exact chat in the Agents Window, and an NCF Agent Interconnect service restart and Cursor window reload followed by an ordinary message. The existing AionUi integration with Cursor Agent also passed on macOS. A full Cursor application Quit and restart was not tested. On Windows Cursor 3.27.22, Cancel and Apply passed in the source application UI and preserved unrelated data; native chat exchange and AionUi verification were not run in that cycle.

In a later owner-led Windows check with Cursor 3.29.9, a direct IDE chat and Cursor Agent in AionUi each completed a separate ping/pong exchange with recipient acknowledgment. Open unselected chats, Agents Window delivery and restart recovery were not checked in that Windows cycle. An exact-package preview separately passed its bundled-runtime check; the live chat exchanges did not establish which NCF Agent Interconnect process revision handled them.

The new existing-chat recovery behavior has source-level regression coverage. Native validation of this recovery cycle has not yet been reported.

## OpenCode and its frontends

Choose OpenCode, open **Configure OpenCode** and select the configuration that instance actually loads, such as its global `opencode.json` or `opencode.jsonc`. Apply configures both the MCP connection and bundled plugin. Restart OpenCode after adding the plugin. A frontend must use that OpenCode instance and load its plugins. No per-chat port, password or session setup is required. This dialog supports OpenCode v1; v2 configuration is not supported.

## Codex Desktop

Choose Codex, open **Configure Codex** and select the intended profile's `config.toml`. Click Apply and reconnect MCP in that profile. Automatic delivery to the exact chat is experimental and depends on the installed Codex Desktop version. If the intended chat cannot be identified, NCF Agent Interconnect reports the condition rather than selecting another chat.

## AionUi with Cursor Agent

The supported setup is Cursor Agent inside AionUi. Its page guides you through **Authorization**, **MCP settings** and **Live bridge**. Complete local WebUI access with native owner confirmation. Separately open **Configure Cursor Agent** and Apply the shared MCP entry to the selected Cursor configuration file. The dialog explains that both setups use the same MCP entry when the same file is selected. Only **Configure Cursor** installs the direct Cursor plugin. Reconnect Cursor Agent in the intended AionUi chat to reload MCP settings, then connect an agent there. Owner authorization, saved settings and a live chat bridge are separate states. Other AionUi backends are not covered by this setup. See the [AionUi with Cursor Agent setup guide](aionui-setup.md).

## Claude Code

Choose Claude Code and click Configure Claude Code. Apply enables the NCF main
and gate plugins from the marketplace published by this app in the selected
Claude Code user `settings.json` and allows `agent_read` without a prompt.
Other settings and permissions survive; `~/.claude.json` is never edited.
Start or resume Claude Code normally, then connect an agent in the intended
chat. The native mod delivers full Incoming messages directly to the model and
visible exact chat with sender, body, attachment links and the reply route.
Automatic delivery does not call `agent_read`; explicit manual reads remain available. In auto mode, use Claude's
native `/permissions` dialog to grant only the exact additional tools you
intend to allow, such as `agent_connect` and `agent_send`. These grants remain
your choice; NCF Agent Interconnect does not add broader write permissions automatically. See
[Claude Code setup and limits](https://github.com/no-colours-fabric/ncf-agent-interconnect/blob/main/docs/claude-code-adapter.md).

## Other clients

Other compatible MCP clients can exchange messages and read history. The desktop app's Configure and Apply flow is available for Cursor, OpenCode v1, Codex Desktop, Cursor Agent in AionUi and Claude Code. Automatic delivery to an idle chat requires a client adapter.

In any configured chat, ask the assistant to connect under the name you choose and give it a task that relates to another agent's work. For example: “Connect as agent Iris. Review agent Sam’s search requirements and report any gaps to Sam.” This is an illustrative chat request, not fixed syntax. If the name is occupied by another chat, moving it requires your explicit choice. [Work with agents from your chats](usage.md) explains the normal task workflow.
