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

> Learn to use the OpenWork MCP server in Claude Code, Codex, and OpenCode. Configure remote endpoints or local stdio connections and control the OpenWork desktop UI programmatically.

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

---

**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](https://github.com/different-ai/openwork/blob/dev/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:

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

```

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

```text
> 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](https://github.com/different-ai/openwork/blob/dev/README.md#claude-code) 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:

```bash
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:

```text
> !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](https://github.com/different-ai/openwork/blob/dev/README.md#codex).

## 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`](https://github.com/different-ai/openwork/blob/main/opencode.json):

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

```js
// 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](https://github.com/different-ai/openwork/blob/dev/README.md#opencode).

## Local stdio MCP Setup for Offline Use

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

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

```

Then reference it as a local server in OpenCode:

```json
{
  "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:

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

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](https://github.com/different-ai/openwork/blob/dev/docs/mcp-ui-control-profile.md#add-to-your-own-mcp-client).

## Key Source Files in the OpenWork Repository

| File | Relevance |
|------|-----------|
| [`docs/mcp-ui-control-profile.md`](https://github.com/different-ai/openwork/blob/main/docs/mcp-ui-control-profile.md) | Complete MCP server documentation, tool reference, and installation steps. |
| [`README.md`](https://github.com/different-ai/openwork/blob/main/README.md) | Quick-start commands for Claude Code, Codex, and OpenCode. |
| [`packages/types/src/den/mcp-connection-action.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/den/mcp-connection-action.ts) | TypeScript definitions for MCP connection actions. |
| [`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) | 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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/docs/mcp-ui-control-profile.md) and [`packages/types/src/den/mcp-connection-action.ts`](https://github.com/different-ai/openwork/blob/main/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.