How to Integrate OpenWork with Existing AI Agents: A Complete MCP Guide

Integrating OpenWork with existing AI agents requires connecting to the Model-Connect-Protocol (MCP) endpoint at https://api.openworklabs.com/mcp/agent, which exposes organizational skills through standardized search_capabilities and execute_capability methods.

The different-ai/openwork repository provides a headless MCP gateway that allows any AI agent to reuse OpenWork capabilities without installing the desktop application. This guide explains how to connect your existing agents to the OpenWork ecosystem using the MCP interface defined in AGENTS.md and implemented across the TypeScript codebase.

Understanding the OpenWork MCP Architecture

OpenWork exposes its functionality through a standardized MCP server that acts as a remote gateway for organizational skills and plugins.

The MCP Server Endpoint

The central entry point for agent integration is hosted at https://api.openworklabs.com/mcp/agent. According to the source code in packages/types/src/den/mcp-connection-action.ts, this endpoint handles connection actions that publish and sync capabilities between the OpenWork Den (enterprise control plane) and connected agents.

When an agent connects to this endpoint, it gains access to two primary methods:

• search_capabilities: Returns a JSON catalog of available skills, plugins, and external connections (Google Workspace, Microsoft 365, and custom tools)
• execute_capability: Runs a selected capability with provided arguments

Skills, Plugins, and Provider Types

Each capability in OpenWork is classified using the Zod schema defined in packages/types/src/openwork-affordance.ts. The openworkProviderKindSchema distinguishes providers into four categories:

• builtin: Core OpenWork functionality
• extension: Third-party plugins
• mcp: External MCP-compatible services
• connect: Custom integrations

When your agent calls search_capabilities, it receives descriptors for each provider type, allowing granular selection of organizational tools.

Step-by-Step Integration Guide

Configure the MCP Endpoint

Add the OpenWork MCP server to your agent's configuration. The method varies by agent type, but all require the same base URL.

For agents using JSON configuration, create an entry pointing to the remote MCP:

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

Authenticate Your Agent

When the MCP is first added, the agent initiates an OAuth flow. The client opens a browser window directing the user to sign in to their OpenWork organization. After successful authentication, a bearer token is stored in a temporary JSON file (e.g., tmp/dev-headless-web.json) and used for subsequent API calls.

This token persists across sessions but never appears in the UI bundle, maintaining security while allowing headless operation. For local development, you can use the headless web mode to streamline authentication:

pnpm dev:headless-web

This command launches the Vite development server and prints a URL for browser-based sign-in.

Discover and Execute Capabilities

Once authenticated, your agent can interact with the OpenWork skill catalog:

1. Discovery: Call search_capabilities to retrieve the current catalog synced from the OpenWork Den
2. Execution: Invoke execute_capability with the skill ID and parameters

The MCP periodically syncs with the Den to ensure agents always see the latest published plugins, as implemented in the connection action handlers.

Code Examples for Popular AI Agents

OpenCode Configuration

Add the following to your opencode.json file:

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

Codex CLI Setup

Register the OpenWork MCP using the Codex command-line interface:

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

Claude Code Integration

For Claude Code, use the following command to add the transport layer:

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

Custom JavaScript Implementation

For agents built with custom JavaScript or TypeScript:

// Discover available capabilities
const caps = await agent.search_capabilities();
console.log(caps.filter(c => c.provider === "openwork"));

// Execute a specific skill
await agent.execute_capability({
  name: "mail-send",
  args: {
    to: "team@example.com",
    subject: "Project update",
    body: "The latest build is deployed."
  }
});

Publishing Custom Skills to the MCP

After integrating the base MCP, you can extend functionality by publishing custom skills. New skills are added to the packages/plugins directory as self-contained TypeScript modules.

To sync custom skills to the MCP catalog:

# Add your skill under packages/plugins/my-skill

pnpm dev

The development profile automatically syncs new skills to the MCP, making them immediately available to all connected agents without redeployment.

Summary

• OpenWork uses an MCP gateway at https://api.openworklabs.com/mcp/agent to expose organizational capabilities to external agents.
• Two core methods—search_capabilities and execute_capability—enable discovery and execution of skills.
• Authentication occurs via browser-based OAuth, with tokens stored securely in temporary JSON files rather than the UI bundle.
• Provider types are classified in packages/types/src/openwork-affordance.ts using the openworkProviderKindSchema.
• Configuration varies by agent (OpenCode uses opencode.json, Codex and Claude Code use CLI commands), but all point to the same MCP endpoint.
• Custom skills can be published through the OpenWork Den or by adding plugins to packages/plugins and running pnpm dev.

Frequently Asked Questions

What is the OpenWork MCP and how does it differ from the desktop app?

The OpenWork MCP (Model-Connect-Protocol) is a headless gateway that exposes the same skills and plugins as the desktop application but without the Electron shell. While the desktop client runs openwork-server locally with a UI, the MCP allows any external agent to connect via HTTP to https://api.openworklabs.com/mcp/agent and execute capabilities remotely. This enables integration with Codex, Claude Code, and custom agents without requiring the desktop installation.

How does authentication work when integrating OpenWork with third-party agents?

When you add the OpenWork MCP to an agent, the system opens a browser for OAuth authentication with your OpenWork organization. After sign-in, a bearer token is stored in a temporary JSON file (such as tmp/dev-headless-web.json). This token is used for subsequent API calls to search_capabilities and execute_capability. The token management is handled automatically by the MCP client implementation, ensuring credentials never expose in UI bundles or agent configurations.

Can I use OpenWork capabilities without connecting to the enterprise Den?

Yes. While the OpenWork Den serves as the enterprise control plane for managing teams and model quotas, it is optional for local development. Agents can connect directly to the public MCP URL without Den configuration. However, publishing new organizational skills or managing team-wide access requires the Den, as the sync logic in packages/types/src/den/mcp-connection-action.ts handles capability distribution from the Den to the MCP catalog.

What types of providers can agents access through the OpenWork MCP?

According to packages/types/src/openwork-affordance.ts, agents can access four provider types defined by openworkProviderKindSchema: builtin (core OpenWork tools), extension (third-party plugins), mcp (external MCP-compatible services), and connect (custom organizational integrations). This classification allows agents to filter capabilities by source and trust level when calling search_capabilities.

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