How to Integrate OpenWork with Other Systems: MCP, Plugins, and Connection APIs Explained

OpenWork integrates with external systems through four primary mechanisms: the Managed Capability Provider (MCP) protocol for AI agent discovery, plugin-based capability extensions, declarative skill authoring, and OAuth-backed connection actions for external services.

OpenWork is architected as a composable integration platform designed to bridge AI agents, enterprise tools, and custom workflows. Whether you're connecting a local automation script, a remote LLM agent, or a full-stack application, understanding these integration surfaces—implemented in the different-ai/openwork repository—is essential for effective system interoperability.

OpenWork MCP: The Primary Integration Interface

The Managed Capability Provider (MCP) serves as OpenWork's core integration protocol. It exposes organization capabilities through a thin HTTP JSON-RPC gateway that any compatible AI agent can consume.

MCP Architecture and Methods

As implemented in the source code, the MCP endpoint at https://api.openworklabs.com/mcp/agent publishes two fundamental RPC methods:

• search_capabilities – Discovers available skills, plugins, and connections scoped to the authenticated organization
• execute_capability – Invokes a discovered capability with provided input parameters

The request routing logic resides in [packages/enterprise-mcp-mock-server/src/protocol/mcp-handler.ts](https://github.com/different-ai/openwork/blob/dev/packages/enterprise-mcp-mock-server/src/protocol/mcp-handler.ts), which handles handshakes, tool discovery, and execution dispatching.

Configuring Agents for OpenWork MCP Integration

Add the MCP to a Codex-compatible client:

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

Or configure via opencode.json:

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

The MCP abstracts all underlying implementation details, allowing agents to focus on capability invocation rather than transport mechanics.

Plugin System: Extending OpenWork Capabilities

Plugins are server-side modules—first-party or user-created—that expose new capabilities to the OpenWork ecosystem. They represent the primary extension point for custom tools, data sources, and workflow integrations.

Plugin Schema and Creation Flow

Plugin payloads must conform to the schema defined in [packages/types/src/plugin-flow-app.ts](https://github.com/different-ai/openwork/blob/dev/packages/types/src/plugin-flow-app.ts). The creation flow uses the /v1/plugins REST endpoint:

// Example: Creating a plugin via HTTP POST
const payload = {
  schemaVersion: "1",
  event: "plugin_access_granted",
  pluginId: null,
  pluginName: "Echo Plugin",
  description: "Returns the supplied text unchanged"
};

const response = await fetch("https://api.openworklabs.com/v1/plugins", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload)
});

const { pluginId } = await response.json(); // Returns plg_... identifier

The end-to-end specification in [evals/specs/workflows.e2e.test.ts](https://github.com/different-ai/openwork/blob/dev/evals/specs/workflows.e2e.test.ts) demonstrates complete plugin creation, skill binding, and execution workflows programmatically.

Plugin-Runtime Relationship

Plugin implementations execute independently of the OpenWork control plane. The MCP routes invocations to the registered plugin endpoint, which handles actual computation and returns results through the standard JSON-RPC response envelope.

Skill Authoring: Declarative Capability Definition

Skills are reusable, declarative logic units—authored in markdown or JSON—that agents can discover and invoke. They bridge high-level intent to plugin-backed execution.

Skill Structure and Plugin Binding

A skill references its implementing plugin via the pluginId field:

---
name: Echo Skill
description: Returns the same text you send.
pluginId: plg_abcdef1234  # Reference to previously created plugin

---
{{input}}

Skills support three visibility scopes:

• Private – Accessible only to the creating user
• Organization-wide – Available across the entire tenant
• Team-scoped – Limited to specific organizational units

Skill Invocation via MCP

Agents invoke skills through the standard MCP interface:

{
  "method": "execute_capability",
  "params": {
    "capability": "skill:Echo Skill",
    "input": "Hello OpenWork!"
  },
  "id": 1
}

The MCP resolves the skill reference, retrieves associated plugin configuration, and dispatches execution to the appropriate runtime.

Connection Actions: OAuth and External Service Integration

Connection actions handle structured authentication and interaction flows with external services—Google Workspace, Microsoft 365, ServiceNow, and similar platforms.

MCP Connection Action Schema

Connection actions are implemented as MCP apps following the schema in [packages/types/src/den/mcp-connection-action.ts](https://github.com/different-ai/openwork/blob/dev/packages/types/src/den/mcp-connection-action.ts). This schema defines:

• OAuth/OIDC flow parameters
• Service-specific action definitions
• Credential rotation and refresh mechanics

When provisioned, connection actions appear as standard capabilities in search_capabilities responses, allowing agents to trigger external service operations without managing authentication state.

Connection Action Provisioning Pattern

// Conceptual flow based on schema structure
const connectionAction = {
  type: "mcp_connection_action",
  serviceProvider: "google_workspace",
  oauthConfig: {
    clientId: "....",
    scopes: ["drive.readonly", "calendar.events"]
  },
  actions: [
    { name: "list_files", endpoint: "/drive/v3/files" },
    { name: "create_event", endpoint: "/calendar/v3/events" }
  ]
};

The OpenWork Den control plane manages token lifecycle, refreshing credentials automatically before dispatching to the underlying plugin implementation.

OpenWork Den: Control Plane and Mock Infrastructure

OpenWork Den serves as the organizational metadata store and MCP runtime. It maintains:

• Plugin registries and versions
• Skill definitions and scope mappings
• Connection credentials (encrypted at rest)
• Model quota and usage tracking

Enterprise MCP Mock Server

For integration testing, the repository includes packages/enterprise-mcp-mock-server, with the entry point at [src/runtime/mock-server.ts](https://github.com/different-ai/openwork/blob/dev/packages/enterprise-mcp-mock-server/src/runtime/mock-server.ts). This mock server replicates production MCP behavior for CI pipelines and local development:

# Start local MCP server for testing

cd packages/enterprise-mcp-mock-server
npm run start:mock

The mock server implements identical protocol semantics, enabling safe integration testing without production credential exposure.

Complete Integration Example

This example demonstrates the full integration flow from agent configuration through capability execution:

Step 1: Agent MCP Configuration

{
  "mcpServers": {
    "openwork": {
      "url": "https://api.openworklabs.com/mcp/agent",
      "headers": {
        "Authorization": "Bearer ${OPENWORK_TOKEN}"
      }
    }
  }
}

Step 2: Plugin Creation

// packages/integration-examples/src/create-plugin.ts
const plugin = await openwork.plugins.create({
  name: "Database Query Plugin",
  description: "Execute read-only SQL against configured data sources",
  webhookUrl: "https://my-runtime.example.com/openwork-handler",
  authentication: {
    type: "hmac",
    secretEnvVar: "OPENWORK_WEBHOOK_SECRET"
  }
});

Step 3: Skill Definition

# skills/analytics-query.md

---
name: Analytics Query
description: Run analytics queries against the data warehouse
pluginId: plg_analytics_789xyz
inputSchema:
  type: object
  properties:
    sql:
      type: string
      description: Valid SQL SELECT statement
    timeoutMs:
      type: integer
      default: 30000
---

Execute the following query with timeout {{timeoutMs}}ms:

```sql
{{sql}}

**Step 4: Agent Discovery and Execution**

```typescript
// Agent-side discovery
const capabilities = await mcpClient.request("search_capabilities", {
  filter: "skill:Analytics Query"
});

// Execution
const result = await mcpClient.request("execute_capability", {
  capability: "skill:Analytics Query",
  input: {
    sql: "SELECT COUNT(*) FROM events WHERE created_at > NOW() - INTERVAL '7 days'",
    timeoutMs: 60000
  }
});

Summary

• OpenWork MCP provides the primary integration surface through JSON-RPC over HTTPS, implementing capability discovery and execution protocols
• Plugins extend platform capabilities via the schema defined in packages/types/src/plugin-flow-app.ts, created through the /v1/plugins endpoint
• Skills offer declarative, reusable logic units that bind to plugins and surface through MCP discovery
• Connection actions enable OAuth-backed external service integration through the schema in packages/types/src/den/mcp-connection-action.ts
• OpenWork Den serves as the control plane, with the mock server in packages/enterprise-mcp-mock-server supporting test-driven integration development

Frequently Asked Questions

What authentication does OpenWork MCP require?

OpenWork MCP uses OAuth 2.0 bearer tokens obtained through the OpenWork sign-in flow. Agents must include a valid token in the Authorization header. The mock server accepts test tokens configured via environment variables for development scenarios.

Can I run OpenWork MCP locally without the cloud service?

Yes. The enterprise-mcp-mock-server package provides a complete local MCP implementation. Reference [packages/enterprise-mcp-mock-server/src/runtime/mock-server.ts](https://github.com/different-ai/openwork/blob/dev/packages/enterprise-mcp-mock-server/src/runtime/mock-server.ts) for startup configuration and [src/protocol/mcp-handler.ts](https://github.com/different-ai/openwork/blob/dev/packages/enterprise-mcp-mock-server/src/protocol/mcp-handler.ts) for protocol behavior customization.

How do plugins handle sensitive credentials?

Plugins receive HMAC-signed webhook requests from OpenWork, verified using secrets configured at creation time. Connection actions store OAuth tokens encrypted in OpenWork Den, with refresh handled automatically—plugins receive only short-lived access tokens at invocation time.

What limits exist on skill or plugin execution?

OpenWork Den enforces organization-level quotas on model tokens and plugin invocations. Specific limits depend on the subscription tier. The mock server does not enforce quotas, making it suitable for load testing plugin implementations independently of platform constraints.

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