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

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 and 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:

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.

Add this to your project root:

// 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:

npm install -g openwork-ui-mcp

Then add to your Codex MCP configuration (codex_mcp.json):

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

Execute tools directly from the CLI:

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 demonstrates the transport validation approach.

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	High-level overview and quick-start	Root directory
docs/mcp-ui-control-profile.md	Complete MCP UI control specification	docs/
opencode.json	Example MCP configuration for OpenCode	Root directory
packages/types/src/openwork-affordance.ts	TypeScript definitions for all MCP tools	packages/types/src/
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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}