How to Integrate OpenWork with Other Tools: A Complete MCP Integration Guide

OpenWork exposes skills, plugins, and third-party connectors through a Model-Control-Plane (MCP) architecture, allowing any compatible AI agent to discover and execute capabilities via a JSON-RPC endpoint.

The different-ai/openwork repository provides a modular integration framework that enables you to integrate OpenWork with other tools using standardized MCP protocols. By configuring a remote MCP endpoint, you can expose capabilities like GitHub management, Google Workspace operations, and custom skills to any AI agent that supports the Model-Control-Plane specification.

Understanding OpenWork's MCP Architecture

OpenWork is built around a modular MCP architecture with distinct layers handling different integration concerns.

Remote MCP Endpoint

The core integration point resides in dev/apps/server/src/workspaces.ts, which implements a JSON-RPC-style API under the /v1/* route. This endpoint handles capability discovery and execution requests from external agents, serving as the primary interface to access OpenWork's functionality.

Connector Framework

External services like GitHub, Google Workspace, and Microsoft 365 are wrapped as connectors in dev/packages/enterprise-mcp-mock-server/src/protocol/oauth-handler.ts. Each connector implements OAuth flows, request routing, and fault handling, exposing third-party APIs as standardized MCP tools that agents can invoke without knowing the underlying service details.

Skill and Plugin Registry

Skill definitions are stored as Markdown files and parsed by the registry code in dev/ee/packages/utils/src/skill-markdown.ts. When agents request available capabilities, the MCP serves these skill definitions alongside connector tools, providing metadata about what actions can be performed.

Step-by-Step Integration Process

Integrating OpenWork follows a four-step pattern that any MCP-compatible agent can implement.

1. Configure the Remote MCP URL

Add the OpenWork MCP endpoint to your agent's configuration file. For OpenCode, this means updating opencode.json:

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

2. Discover Available Capabilities

The agent calls the search_capabilities method via POST request to the MCP endpoint. The workspace handler in dev/apps/server/src/workspaces.ts processes this request, returning a list of installed skills, plugins, and connectors (such as github or google-workspace) that the agent can utilize.

3. Execute Capabilities

When performing an action, the agent invokes execute_capability with the target capability name and arguments. The MCP routes this request to the appropriate connector, handling authentication token exchange through the OAuth handler.

4. Handle Connector-Specific Workflows

Each connector implements its own API routes under /v1/connectors/{connector-name}/*. For example, the GitHub connector provides endpoints for listing accounts, repositories, and performing repository actions, as demonstrated in the test specification dev/evals/specs/github-connector-import.slow.test.ts.

Code Examples for Common Integrations

These runnable examples demonstrate how to interact with OpenWork's MCP from different contexts.

Adding OpenWork to OpenCode Configuration

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

Discovering Capabilities with Node.js

import { fetch } from "node-fetch";

async function listCapabilities() {
  const resp = await fetch("https://api.openworklabs.com/mcp/agent/search_capabilities", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: "" })
  });
  const { capabilities } = await resp.json();
  console.log("Available:", capabilities.map(c => c.name));
}

listCapabilities();

The /search_capabilities handler is implemented in the server's workspace module at dev/apps/server/src/workspaces.ts.

Executing GitHub Connector Tools

import { fetch } from "node-fetch";

async function createIssue(repo, title, body) {
  const payload = {
    connector: "github",
    tool: "create_issue",
    args: { repo, title, body }
  };
  
  const resp = await fetch("https://api.openworklabs.com/mcp/agent/execute_capability", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload)
  });
  
  const result = await resp.json();
  console.log("Issue created:", result);
}

createIssue("myorg/myrepo", "Bug report", "Steps to reproduce...");

This example follows the pattern established in dev/evals/specs/github-connector-import.slow.test.ts, where the GitHub connector routes requests to /v1/connectors/github/* endpoints.

Optional Den Control-Plane Integration

For enterprise deployments, OpenWork provides an optional SaaS component called Den. Located in dev/apps/server/src/workspace-init.ts, Den centralizes model-provider selection, team-level access control, and marketplace publishing. To use Den instead of the public SaaS endpoint, point your MCP configuration to your private Den URL, enabling organization-wide skill publishing and fine-grained access controls.

Summary

• MCP Architecture: OpenWork uses a Model-Control-Plane architecture with endpoints defined in dev/apps/server/src/workspaces.ts to expose capabilities via JSON-RPC.
• Connector Framework: Third-party integrations are handled through OAuth-enabled connectors in dev/packages/enterprise-mcp-mock-server/src/protocol/oauth-handler.ts.
• Configuration: Add the remote MCP URL https://api.openworklabs.com/mcp/agent to your agent's configuration file to enable integration.
• Execution Flow: Use search_capabilities to discover tools and execute_capability to invoke them, with the MCP handling routing to specific connectors like GitHub or Google Workspace.
• Enterprise Option: Deploy the Den control-plane via dev/apps/server/src/workspace-init.ts for centralized management and access control.

Frequently Asked Questions

What is the MCP endpoint URL for OpenWork?

The standard public endpoint is https://api.openworklabs.com/mcp/agent. When configuring your AI agent, add this URL to the MCP configuration block under the "openwork" key, setting the type to "remote" and enabling OAuth as needed.

How does OpenWork handle authentication for third-party services?

Authentication is managed by the connector framework implemented in dev/packages/enterprise-mcp-mock-server/src/protocol/oauth-handler.ts. This module handles OAuth flows, token exchange, and fault injection for services like GitHub, Google Workspace, and Microsoft 365, ensuring secure access without exposing credentials to the AI agent.

Can I integrate OpenWork with Claude Code or other AI agents?

Yes, any MCP-compatible agent—including Claude Code, Codex, and OpenCode—can integrate with OpenWork. You simply add the remote MCP configuration to your agent's settings file (such as opencode.json for OpenCode), and the agent will automatically discover and execute OpenWork capabilities through the standardized MCP interface.

What is the Den control-plane and when should I use it?

Den is an optional SaaS component defined in dev/apps/server/src/workspace-init.ts that provides centralized model provisioning, team-level access control, and marketplace publishing for skills. Use Den when you need organization-wide governance over model providers, fine-grained access controls, or private skill distribution rather than connecting directly to the public OpenWork endpoint.

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