How to Configure OpenWork MCP with External AI Agents: Claude Code, Codex, and Cursor

Set the DEN_MCP_RESOURCE_URL environment variable to expose your OpenWork MCP endpoint, then authenticate Claude Code, Cursor, or Codex via OAuth PKCE-S256 to enable secure tool discovery and capability execution.

The different-ai/openwork repository provides a Model Context Protocol (MCP) server that standardizes how external AI agents access your organization's skills. By configuring the MCP endpoint documented in .opencode/skills/shadcn/mcp.md and completing the agent-specific OAuth flows, you can extend Claude Code, Codex, and Cursor with your internal OpenWork capabilities.

OpenWork MCP Architecture

The MCP implementation consists of a centralized HTTP endpoint that handles tool discovery, OAuth token exchange, and capability execution on behalf of external agents.

The MCP Server Endpoint

The MCP server exposes an HTTP endpoint at /mcp/agent that implements the OpenWork MCP API. This endpoint handles tool discovery via /tools/list (with pagination cursors), OAuth flows, and executes capabilities through the execute_capability method.

In dev/packages/openwork-ui-mcp/index.mjs, the server initializes the MCP handler that routes requests from external agents to the appropriate OpenWork services.

Environment Configuration

Configure the public URL that agents must reach using the DEN_MCP_RESOURCE_URL environment variable. This variable is defined in dev/.env.dev and defaults to http://localhost:<DEN_API_PORT>/mcp for local development.

For production deployments, set this to your public HTTPS endpoint:

# docker-compose.yml

services:
  den-api:
    environment:
      - DEN_MCP_RESOURCE_URL=https://api.openworklabs.com/mcp/agent
      - DEN_MCP_ADDITIONAL_RESOURCES=https://openwork.example.internal/api/den/mcp/agent

Reference the Helm configuration in dev/packaging/helm/openwork-ee/templates/configmap.yaml for Kubernetes deployments.

Security and OAuth Implementation

OpenWork enforces PKCE-S256 (Proof Key for Code Exchange) for all OAuth flows to prevent authorization code interception attacks. The MCP server validates PKCE verifiers before issuing session tokens.

Capability definitions are stored in the capability store, typed in dev/packages/types/src/den/mcp-connection-action.ts, and surfaced to agents through the MCP catalog.

Configuring Claude Code

Claude Code connects to OpenWork using a standard HTTPS OAuth callback flow.

Connector Setup

1. Open the Connectors pane in Claude Code and paste your MCP URL (e.g., https://api.openworklabs.com/mcp/agent).

2. Type /mcp in any chat session and select OpenWork to initiate the connection.

Authentication Flow

Claude Code uses a standard HTTPS redirect URI (e.g., https://<your-domain>/callback). The MCP server validates the PKCE-S256 verifier provided by Claude Code, issues a short-lived session token, and stores the association in the MCP token store.

Detailed UI flows are documented in dev/packages/docs/model-context-protocol/claude-code.mdx.

Configuring Claude Desktop

Claude Desktop follows a similar pattern to Claude Code but maintains separate client registration.

1. Navigate to Settings > Connectors in Claude Desktop and paste the same MCP URL used for Claude Code.

2. Complete the OAuth flow using the HTTPS redirect URI.

3. After authorization, use /mcp commands to resolve OpenWork capabilities and execute tools.

Reference the desktop-specific implementation in dev/packages/docs/model-context-protocol/claude-desktop.mdx.

Configuring Cursor

Cursor Desktop requires special handling for its private-use URI scheme callback.

Desktop Integration

1. Open Settings > Connectors in Cursor Desktop and paste your MCP endpoint URL.

2. Initiate the OAuth flow; Cursor will request authorization using its private callback scheme.

Private-Use URI Scheme

Cursor Desktop uses the cursor://anysphere.cursor-mcp/oauth/callback URI scheme for OAuth redirects. The MCP server contains an explicit allow-list entry for this scheme and enforces PKCE-S256 validation to prevent code-replay attacks.

After the user authorizes in the browser, Cursor receives the authorization code via the custom scheme, validates the PKCE verifier, and exchanges it for an MCP session token. The agent can then list tools via /tools/list and invoke execute_capability as documented in dev/packages/docs/model-context-protocol/cursor.mdx.

Configuring Codex and Other MCP Clients

Any MCP-compliant agent, including Codex, can connect to OpenWork using the same /mcp/agent endpoint. Configure these clients with your public MCP URL and ensure their OAuth redirect URIs are allow-listed in the MCP server configuration. The standardized protocol ensures that tools/list and execute_capability requests function identically across all supported agents.

Implementation Examples

Node.js Client Usage

Use the Enterprise MCP client to interact with the protocol programmatically:

import { EnterpriseMcpClient } from '@openwork/enterprise-mcp-client';

const client = new EnterpriseMcpClient({
  baseUrl: process.env.DEN_MCP_RESOURCE_URL,
  token: process.env.OPENWORK_MCP_TOKEN,
});

// List available tools with pagination
let cursor;
do {
  const { tools, nextCursor } = await client.listTools(
    cursor ? { cursor } : undefined
  );
  console.log('Tools:', tools.map(t => t.name));
  cursor = nextCursor;
} while (cursor);

// Execute a capability
await client.executeCapability({
  capability: 'run_script',
  args: { path: '/tmp/hello.sh' },
});

This implementation is based on dev/packages/enterprise-mcp-client/src/tool-catalog.ts.

Skill Manifest Configuration

Define MCP connectivity in your plugin manifest:

{
  "name": "my-plugin",
  "mcp": {
    "url": "https://api.openworklabs.com/mcp/agent",
    "clientId": "openwork",
    "scopes": ["execute_capability"]
  },
  "tools": [
    {
      "name": "run_script",
      "description": "Runs a shell script on the host.",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": { "type": "string" }
        }
      }
    }
  ]
}

Validating Configuration

Run the parity check script to ensure your MCP URLs are correctly registered across the installer UI and documentation:

node dev/scripts/check-connect-installer-parity.mjs

This script verifies that references in dev/.opencode/skills/shadcn/mcp.md match the actual implementation in the connector interfaces.

Summary

• Set DEN_MCP_RESOURCE_URL to expose the /mcp/agent endpoint publicly.
• Use PKCE-S256 OAuth for all agent connections, with Cursor requiring the special cursor:// callback scheme.
• Reference agent-specific docs in dev/packages/docs/model-context-protocol/ for Claude Code, Claude Desktop, and Cursor.
• Validate setups using check-connect-installer-parity.mjs to ensure URL consistency.
• Implement clients using @openwork/enterprise-mcp-client for programmatic access to tool discovery and capability execution.

Frequently Asked Questions

What is the exact MCP endpoint URL for OpenWork?

The default endpoint is /mcp/agent relative to your API base URL. Set the full public URL via the DEN_MCP_RESOURCE_URL environment variable, for example https://api.openworklabs.com/mcp/agent.

How does OpenWork prevent unauthorized MCP access?

All agent connections require OAuth PKCE-S256 flow. The MCP server validates PKCE verifiers and issues short-lived session tokens. Cursor-specific protections include allow-listing the private-use URI scheme cursor://anysphere.cursor-mcp/oauth/callback.

Can multiple AI agents connect to the same OpenWork instance simultaneously?

Yes. The MCP server handles concurrent connections from Claude Code, Claude Desktop, Cursor, and other agents. Each connection maintains independent OAuth tokens while sharing the same capability definitions from the OpenWork catalog.

Where are MCP tool definitions stored?

Tool and capability definitions are typed in dev/packages/types/src/den/mcp-connection-action.ts and surfaced through the MCP server's tool catalog, which agents query via the /tools/list endpoint with pagination support.

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