Cowork Desktop Setup

Omnodex integrates with Cowork through a plugin that routes MCP tool calls through the Omnodex proxy. Every call to an MCP server you route through Omnodex is recorded in your local event log.

How this differs from Claude Code

The Claude Code integration uses hooks and records built-in tools such as file reads, edits, and shell commands. The Cowork integration uses the MCP proxy, so it records MCP tool calls. Cowork does not currently run plugin-contributed hooks (anthropics/claude-code#27398, #40495), so its built-in tools are not recorded.

Where the proxy runs

The plugin’s MCP server runs on your desktop, including for Cowork tasks you start from the cloud: those tasks start plugin MCP servers on the desktop linked to your account. Everything below happens on that desktop. On Windows, that is native Windows, not WSL.

Before you start

On the desktop:

1. Install Node.js 24+ natively. The plugin starts the proxy with the system Node.js. On Windows, a Node.js install that exists only inside WSL does not work.
2. Install Omnodex from npm, or from source. On Windows, do this in PowerShell.

Check Node.js:

Windows (PowerShell)

where.exe node
where.exe npx

macOS / Linux / WSL

which node
which npx

Installation

1. Install the plugin.

   Download omnodex-cowork.plugin, then drag it onto the Cowork window, or install it from a file in Settings > Plugins. Confirm omnodex-cowork appears in the installed plugins list and is enabled.

2. Create the proxy configuration.

   Create omnodex-proxy.json in your Omnodex home. upstream_servers lists the MCP servers to route through Omnodex:

   Windows (PowerShell)

   C:\Users\<you>\.omnodex\omnodex-proxy.json:

   {
     "version": 1,
     "redact_parameters": false,
     "upstream_servers": [
       {
         "name": "filesystem",
         "transport": "stdio",
         "command": "C:\\Program Files\\nodejs\\npx.cmd",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\<you>\\Documents\\project"]
       }
     ]
   }

   Use the paths where.exe printed, and Windows paths throughout. JSON strings need escaped backslashes.

   macOS / Linux / WSL

   ~/.omnodex/omnodex-proxy.json:

   {
     "version": 1,
     "redact_parameters": false,
     "upstream_servers": [
       {
         "name": "filesystem",
         "transport": "stdio",
         "command": "/absolute/path/to/npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/<you>/project"]
       }
     ]
   }

   Replace the example upstream with the MCP servers you use. Put secrets in environment variables and reference them as ${VAR} in an upstream’s env. See Configuration.

   Installed from npm

   That is all: the plugin finds the npm install on its own.

   Installed from source

   Also add proxy_bin, the path to your build’s proxy, for example "proxy_bin": "C:\\path\\to\\omnodex\\packages\\mcp-proxy\\dist\\bin\\omnodex-mcp-proxy.js" on Windows or "proxy_bin": "/path/to/omnodex/packages/mcp-proxy/dist/bin/omnodex-mcp-proxy.js" elsewhere. Use proxy_bin rather than an environment variable: Cowork does not pass user environment variables to plugin MCP servers.

3. Fully quit and reopen Cowork.

   Quit the app completely (on Windows, also from the system tray), then open it again. Cowork does not retry a plugin MCP server that failed to start until the app restarts.

4. Verify in a new task.

   Type /omnodex in a new task, or ask Cowork to call omnodex_status. Then ask it to use one of the routed tools. Routed tools appear as <server>__<tool>, for example filesystem__list_directory.

   Cowork asks for approval the first time each tool is used. Choose to allow it for all tasks if you do not want to be asked again.

5. Connect to the hosted dashboard (optional).

   Type /omnodex connect, or ask Cowork to call omnodex_connect. If this desktop has no API token yet, you get a short code and a URL: open the URL, sign in at dashboard.omnodex.com, and enter the code. The passphrase is transferred end-to-end encrypted.

What gets traced

Activity	Recorded	Notes
Calls to MCP servers routed through Omnodex	Yes	Tool name, parameters (unless redacted), timing, status, and response size
Proxy session start and end	Yes	The session ends when Cowork stops the proxy, for example when the app quits
Cowork built-in tools (read, write, shell)	No	Not routed through MCP
MCP servers or connectors not routed through Omnodex	No	Only upstreams in omnodex-proxy.json pass through the proxy

Viewing events

Cowork writes events to the Omnodex home on the desktop: C:\Users\<you>\.omnodex\ on Windows, ~/.omnodex/ on macOS and Linux.

Windows (PowerShell)

omnodex dashboard

macOS / Linux

omnodex dashboard

From WSL

WSL has its own Omnodex home, so add the Windows one as an extra root:

omnodex dashboard --roots /mnt/c/Users/<you>/.omnodex

See Windows and WSL.

Updating

1. Update Omnodex on the desktop: run omnodex update in PowerShell on Windows, or your terminal on macOS. It updates an npm install or a source build. See Updating.

2. Check whether the plugin changed. The current version is cowork.version in latest.json. If you already have that version, skip to step 5.

3. Remove the old plugin. In Settings > Plugins, remove omnodex-cowork. Do this before installing the new one, so only one copy of the Omnodex server is registered.

4. Install the new plugin. Download the latest omnodex-cowork.plugin and install it as in Installation, step 1. Your omnodex-proxy.json is outside the plugin, so it is kept.

5. Fully quit and reopen Cowork, including from the system tray on Windows, then start a new task. Tasks that were already open keep the tools they started with.

To check the result, ask Cowork to call omnodex_status in the new task.

Troubleshooting

omnodex_status is not available in Cowork:

1. Check launcher.log in .omnodex under your user home (C:\Users\<you>\.omnodex\launcher.log on Windows). The plugin’s launcher records startup failures there:

   Log entry	Cause
   FATAL: binary not found	The launcher could not find Omnodex. For an npm install, check npm install -g omnodex ran in PowerShell on this desktop, not only in WSL. For a source install, proxy_bin is missing or points to a file that does not exist, or omnodex-proxy.json is not in .omnodex under your user home
   FATAL: spawn error	Node.js could not start the proxy

   The launcher writes only failures, so a log with no new entries does not mean something went wrong.

2. Check that the proxy starts on its own with your config. It should start and wait for input (press Ctrl+C to stop). A config error prints a message and exits.

   Installed from npm

   omnodex-mcp-proxy --config C:\Users\<you>\.omnodex\omnodex-proxy.json

   Installed from source

   node C:\path\to\omnodex\packages\mcp-proxy\dist\bin\omnodex-mcp-proxy.js --config C:\Users\<you>\.omnodex\omnodex-proxy.json

3. Fully quit and reopen Cowork after any fix.

4. On Windows, the Claude desktop app log at %LOCALAPPDATA%\Claude\logs\main.log shows each attempt to start the plugin’s server. Search for omnodex-cowork: a working setup logs Connected to plugin:omnodex-cowork:omnodex, and a failing one logs Failed to connect.

The proxy fails with ERR_MODULE_NOT_FOUND for an @omnodex/... package (Windows): the build was installed from WSL. See Windows and WSL for the fix.

Routed tools fail with requires approval, or approval only offers “once”: update Omnodex. Earlier builds named routed tools <server>/<tool>, which Cowork cannot approve. Rebuild, fully restart Cowork, and start a new task.

Events appear in the wrong place (Windows): Cowork writes to the Windows Omnodex home. A dashboard started in WSL reads the WSL home unless you add the Windows one with --roots.

Next steps

• Windows and WSL
• Running Detection
• Choosing a Dashboard
• Configuration Reference