How to Use the OpenWork MCP Server in Claude Code, Codex, and OpenCode

Set up the OpenWork MCP server by configuring a remote endpoint (https://api.openworklabs.com/mcp/agent) for cloud-based agents or installing the openwork-ui-mcp npm package for local stdio connections, then invoke the four core tools (ui_status, ui_snapshot, ui_list_actions, ui_execute_action) to programmatically control the OpenWork desktop UI.

OpenWork ships a Model Context Protocol (MCP) server that transforms its desktop application into a semantic, scriptable API. According to the OpenWork source code, this lets Claude Code, Codex, OpenCode, and any other MCP-compatible agent discover UI capabilities, execute actions, and drive workflows without DOM scraping or pixel-hunting. The MCP server bridges these agents to the local OpenWork app through a private HTTP connection secured with a bearer token.

How the OpenWork MCP Architecture Works

The OpenWork MCP stack consists of three layers that communicate over stdio and localhost HTTP:

Component	Role
OpenWork desktop app	Runs a private HTTP bridge on a random localhost port and writes a discovery file with the bridge URL and bearer token.
openwork-ui-mcp	A Node.js stdio process that reads the discovery file, forwards MCP tool calls to the bridge, and returns structured responses.
MCP client	Claude Code, Codex, OpenCode, or custom tools that spawn openwork-ui-mcp and issue calls like ui_snapshot or ui_execute_action.

Data flows as follows:

Claude Code / Codex / OpenCode → stdio ↔ openwork-ui-mcp → HTTP bridge ↔ OpenWork desktop

Because the bridge binds to 127.0.0.1, no network traffic leaves your machine. The bearer token in the discovery file ensures only trusted MCP clients can control the UI. For implementation details, see docs/mcp-ui-control-profile.md in the OpenWork repository.

Core MCP Tools for Controlling OpenWork

All agents use the same four standardized tools defined in the OpenWork MCP server:

Tool	Purpose
ui_status	Verify the bridge is reachable and return connection metadata.
ui_snapshot	Capture the current UI route, narration, and visible actions.
ui_list_actions	Retrieve the full catalog of available actions in the current context.
ui_execute_action	Run a UI action by ID with optional arguments.

These tools map directly to UI operations like composer.set_text, composer.send, or session.list_sessions. The ui_execute_action tool accepts an actionId string and an args object, enabling fully programmatic control of OpenWork workflows.

Setting Up the OpenWork MCP Server in Claude Code

Claude Code supports MCP servers via HTTP transport. Add the remote OpenWork endpoint with a single command:

claude mcp add --transport http openwork https://api.openworklabs.com/mcp/agent

Once configured, invoke MCP tools using Claude Code's call tool syntax:

> call tool ui_status {}
{
  "connected": true,
  "bridge": "http://127.0.0.1:52431",
  "version": "1"
}

> call tool ui_list_actions {}
{
  "actions": [
    {"id":"session.list_sessions","label":"List sessions"},
    {"id":"composer.set_text","label":"Type into composer"},
    {"id":"composer.send","label":"Send message"}
  ]
}

> call tool ui_execute_action {"actionId":"session.list_sessions"}
{
  "sessions":[
    {"id":"ses_abc123","title":"Project kickoff"},
    {"id":"ses_def456","title":"Bug triage"}
  ]
}

This setup is documented in the README.md Claude Code section of the OpenWork repository.

Configuring the OpenWork MCP Server in Codex

Codex uses a similar CLI pattern for MCP registration. Add the remote server with:

codex mcp add openwork --url https://api.openworklabs.com/mcp/agent

Codex exposes tools via the !tool prefix. Here is a complete workflow for inspecting the UI and sending a prompt:

> !tool ui_snapshot {}
{
  "route": "/session/ses_abc123",
  "status": "ready",
  "actions": ["composer.set_text","composer.send","session.list_sessions"]
}

> !tool ui_execute_action {"actionId":"composer.set_text","args":{"text":"Summarize the OpenWork architecture"}}
{
  "result":"text set"
}

> !tool ui_execute_action {"actionId":"composer.send"}
{
  "result":"prompt sent"
}

The Codex MCP integration is covered in README.md.

Adding the OpenWork MCP Server to OpenCode

OpenCode uses JSON configuration files rather than CLI commands. Add the following to your workspace or global opencode.json:

{
  "mcp": {
    "openwork": {
      "type": "remote",
      "enabled": true,
      "url": "https://api.openworklabs.com/mcp/agent",
      "oauth": {}
    }
  }
}

OpenCode wraps MCP calls in tools.execute_capability. Here is a runnable script that checks for the composer and sends a message:

// example.mcp.js — OpenWork MCP demo for OpenCode
await tools.execute_capability({
  name: "ui_snapshot",
  arguments: {}
});

const actions = await tools.execute_capability({
  name: "ui_list_actions",
  arguments: {}
});

if (actions.actions.some(a => a.id === "composer.set_text")) {
  await tools.execute_capability({
    name: "ui_execute_action",
    arguments: {
      actionId: "composer.set_text",
      args: { text: "Explain the MCP flow in one sentence" }
    }
  });
  
  await tools.execute_capability({
    name: "ui_execute_action",
    arguments: { actionId: "composer.send" }
  });
}

Run this script with opencode run example.mcp.js. The OpenCode MCP configuration is detailed in README.md.

Local stdio MCP Setup for Offline Use

For fully offline operation or custom tooling, install the openwork-ui-mcp package directly:

npm install -g openwork-ui-mcp

Then reference it as a local server in OpenCode:

{
  "mcp": {
    "openwork-ui": {
      "type": "local",
      "command": ["npx", "-y", "openwork-ui-mcp"],
      "enabled": true
    }
  }
}

The local stdio server reads the discovery file from ~/Library/Application Support/com.differentai.openwork/ (macOS) or equivalent paths on other platforms, then proxies calls to the localhost bridge.

For raw MCP client implementation, use the official SDK:

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);

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

await client.callTool({
  name: "ui_execute_action",
  arguments: {
    actionId: "composer.set_text",
    args: { text: "Hello from a custom Node app" }
  }
});

This pattern works in any Node.js environment and is documented in docs/mcp-ui-control-profile.md.

Key Source Files in the OpenWork Repository

File	Relevance
docs/mcp-ui-control-profile.md	Complete MCP server documentation, tool reference, and installation steps.
README.md	Quick-start commands for Claude Code, Codex, and OpenCode.
packages/types/src/den/mcp-connection-action.ts	TypeScript definitions for MCP connection actions.
packages/enterprise-mcp-mock-server/src/testing/probe.ts	MCP handshake and version negotiation logic for testing.

Summary

• Install the OpenWork MCP server by adding the remote endpoint to Claude Code (claude mcp add), Codex (codex mcp add), or OpenCode (opencode.json).
• Use four standardized tools — ui_status, ui_snapshot, ui_list_actions, and ui_execute_action — to inspect and control the OpenWork UI.
• Choose remote or local mode: the hosted endpoint works everywhere; the openwork-ui-mcp npm package enables offline, custom-client scenarios.
• Reference actual source paths like docs/mcp-ui-control-profile.md and packages/types/src/den/mcp-connection-action.ts to understand implementation details.

Frequently Asked Questions

What is the difference between the remote MCP endpoint and the local stdio server?

The remote endpoint (https://api.openworklabs.com/mcp/agent) is a hosted server that forwards MCP calls to your locally-running OpenWork bridge. It requires no installation and works from any agent. The local stdio server (openwork-ui-mcp) runs entirely on your machine, making it suitable for air-gapped environments or custom client development.

Does using the OpenWork MCP server send my data to the cloud?

No. All UI control traffic flows through a localhost HTTP bridge between openwork-ui-mcp and the OpenWork desktop app. The remote endpoint only acts as a routing layer; no prompt content, session data, or UI state leaves your machine. The bearer token in the discovery file cryptographically secures this local connection.

Which OpenWork UI actions can I trigger through the MCP server?

Any action exposed by the current UI context. Common examples include composer.set_text and composer.send for the chat interface, plus session.list_sessions, session.switch_session, and context-specific actions defined by installed skills. Call ui_list_actions to discover the full set available in your current view.

Can I use the OpenWork MCP server with custom agents or scripts?

Yes. Any client implementing the Model Context Protocol can connect via stdio to openwork-ui-mcp or use the HTTP bridge directly. The @modelcontextprotocol/sdk package provides official client libraries for Node.js, Python, and other runtimes.

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