# How to Integrate different-ai/openwork with Other Tools Using MCP

> Integrate OpenWork with other tools using MCP. Expose your desktop UI as programmatic tools with a simple configuration entry. Learn how to connect OpenWork today.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: how-to-guide
- Published: 2026-08-04

---

**Integrate OpenWork seamlessly with any Model-Context-Protocol (MCP) compatible tool by adding a simple configuration entry that exposes the desktop UI as semantic, programmatic tools.**

OpenWork is designed around a **Model-Context-Protocol (MCP) server** that transforms its desktop interface into discoverable, callable tools. This architecture eliminates the need for brittle screen-scraping or coordinate-based automation. Any MCP-compatible client can query OpenWork's state and invoke actions programmatically—whether you're using Codex, Claude Code, OpenCode, HandsFree, or building a custom integration.

## Understanding the MCP Architecture in OpenWork

The integration relies on three core components working together, as documented in [`README.md`](https://github.com/different-ai/openwork/blob/main/README.md) and [`docs/mcp-ui-control-profile.md`](https://github.com/different-ai/openwork/blob/main/docs/mcp-ui-control-profile.md).

### The Bridge Discovery Mechanism

When OpenWork launches, it writes a **discovery file** to `~/Library/Application Support/com.differentai.openwork/` containing:
- The bridge URL (random localhost port)
- A bearer token for authentication

The `openwork-ui-mcp` wrapper reads this file automatically, establishing a secure local HTTP connection to the Electron-hosted bridge.

### Available MCP Tools

The MCP server exposes four semantic tools defined in [`packages/types/src/openwork-affordance.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/openwork-affordance.ts):

| Tool | Purpose |
|------|---------|
| `ui_status` | Check if OpenWork is running and reachable |
| `ui_snapshot` | Capture current route, UI state, and available affordances |
| `ui_list_actions` | Enumerate all actionable elements on the current screen |
| `ui_execute_action` | Invoke an action by name (e.g., `composer.set_text`) |

This semantic approach means clients interact with **named actions** rather than pixels—making integrations stable across UI updates.

## Integrating OpenWork with OpenCode

OpenCode integration requires adding the MCP server to your project configuration, as shown in [`opencode.json`](https://github.com/different-ai/openwork/blob/main/opencode.json).

Add this to your project root:

```json
// opencode.json
{
  "mcp": {
    "openwork-ui": {
      "type": "local",
      "command": ["npx", "-y", "openwork-ui-mcp"],
      "enabled": true
    }
  }
}

```

Once configured, OpenCode automatically spawns the MCP server on demand. You can then use natural language prompts:

```

> Use ui_snapshot to see what screen OpenWork is on, then list the available sessions.
> Execute composer.set_text with "Summarize this repository" and then send it.

```

## Integrating OpenWork with Codex

Codex integration follows a similar pattern with slightly different configuration syntax.

First, install the MCP wrapper globally:

```bash
npm install -g openwork-ui-mcp

```

Then add to your Codex MCP configuration ([`codex_mcp.json`](https://github.com/different-ai/openwork/blob/main/codex_mcp.json)):

```json
{
  "mcpServers": {
    "openwork-ui": {
      "command": "openwork-ui-mcp",
      "args": []
    }
  }
}

```

Execute tools directly from the CLI:

```bash
codex mcp call ui_status
codex mcp call ui_execute_action '{"actionId":"composer.set_text","args":{"text":"Analyze the codebase"}}'
codex mcp call ui_execute_action '{"actionId":"composer.send"}'

```

## Building Custom Integrations with Node.js

For programmatic control, use the official MCP SDK to connect directly. The pattern in [`packages/enterprise-mcp-mock-server/src/testing/probe.ts`](https://github.com/different-ai/openwork/blob/main/packages/enterprise-mcp-mock-server/src/testing/probe.ts) demonstrates the transport validation approach.

```js
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["-y", "openwork-ui-mcp"],
});

const client = new Client({ name: "my-script", version: "1.0.0" });
await client.connect(transport);

// Verify connection
const status = await client.callTool({ name: "ui_status", arguments: {} });
console.log("OpenWork status:", status);

// Capture current UI state
const snapshot = await client.callTool({ name: "ui_snapshot", arguments: {} });
console.log("Current route:", snapshot.route);

// Interact with the composer
await client.callTool({
  name: "ui_execute_action",
  arguments: {
    actionId: "composer.set_text",
    args: { text: "Explain the architecture of OpenWork" },
  },
});

await client.callTool({
  name: "ui_execute_action",
  arguments: { actionId: "composer.send" },
});

```

This pattern works with any Node.js application—test runners, CI pipelines, or internal tooling.

## No-Code Integration with HandsFree

HandsFree provides a zero-configuration option for users who prefer visual workflows:

1. **Launch OpenWork** — the bridge starts automatically
2. **Open HandsFree** — it scans for MCP servers
3. **Select OpenWork** from the connector panel (shows green "Connected" badge)
4. **Use built-in actions** — `ui_snapshot`, `ui_list_actions`, and `ui_execute_action` appear as draggable workflow blocks

No JSON editing or terminal commands required.

## Security and Local-Only Operation

The integration architecture prioritizes isolation:

- **Localhost binding** — the bridge never exposes ports externally
- **Bearer token authentication** — each session generates unique credentials
- **Random port assignment** — prevents predictable targeting
- **File-system discovery** — credentials transfer via OS-protected paths, never over network

These protections mean you can safely run OpenWork integrations on shared machines or sensitive environments.

## Key Reference Files

| File | Purpose | Location |
|------|---------|----------|
| [`README.md`](https://github.com/different-ai/openwork/blob/main/README.md) | High-level overview and quick-start | Root directory |
| [`docs/mcp-ui-control-profile.md`](https://github.com/different-ai/openwork/blob/main/docs/mcp-ui-control-profile.md) | Complete MCP UI control specification | `docs/` |
| [`opencode.json`](https://github.com/different-ai/openwork/blob/main/opencode.json) | Example MCP configuration for OpenCode | Root directory |
| [`packages/types/src/openwork-affordance.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/openwork-affordance.ts) | TypeScript definitions for all MCP tools | `packages/types/src/` |
| [`packages/enterprise-mcp-mock-server/src/testing/probe.ts`](https://github.com/different-ai/openwork/blob/main/packages/enterprise-mcp-mock-server/src/testing/probe.ts) | Transport validation and testing patterns | `packages/enterprise-mcp-mock-server/src/testing/` |

## Summary

- **OpenWork exposes its UI through a semantic MCP server** (`openwork-ui-mcp`) that bridges to the Electron-hosted HTTP bridge
- **Integration requires only configuration** — add the MCP server entry to your tool's config (OpenCode, Codex, Claude Code, etc.)
- **Four core tools** (`ui_status`, `ui_snapshot`, `ui_list_actions`, `ui_execute_action`) provide complete programmatic control
- **Security is built-in** via localhost binding, bearer tokens, and file-system discovery
- **Custom integrations** use the standard MCP SDK with stdio transport, as demonstrated in the test probe implementation

## Frequently Asked Questions

### What is MCP and why does OpenWork use it?

**MCP (Model-Context-Protocol)** is an open standard for connecting AI systems to external tools and data sources. OpenWork uses MCP because it provides **semantic, stable APIs** that don't break when the UI changes—unlike traditional automation that relies on screen coordinates or DOM selectors. Any MCP-compatible client can discover and use OpenWork's capabilities without custom integration code.

### Do I need to modify OpenWork's source code to integrate with my tools?

No. OpenWork's MCP bridge is **built into the desktop application** and activates automatically on launch. Integration happens entirely through **external configuration**—adding the `openwork-ui-mcp` package to your MCP client's server list. The discovery file mechanism means the wrapper finds OpenWork's bridge without manual URL or token entry.

### Can I integrate OpenWork with tools not officially listed?

Yes. Any tool implementing the **MCP specification** can integrate, including custom scripts, internal company tools, or emerging AI assistants. The [`packages/enterprise-mcp-mock-server/src/testing/probe.ts`](https://github.com/different-ai/openwork/blob/main/packages/enterprise-mcp-mock-server/src/testing/probe.ts) file provides a reference implementation for validating MCP transport connections in new clients.

### What happens if OpenWork isn't running when my MCP client starts?

The `ui_status` tool will return an unavailable state, and other tools will error gracefully. The `openwork-ui-mcp` wrapper continuously monitors the discovery file location, so **starting OpenWork after the MCP client** will enable reconnection without restarting the client. For critical automations, check `ui_status` before calling other tools.