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

> Configure OpenWork MCP with external AI agents like Claude Code, Codex, and Cursor. Set the DEN_MCP_RESOURCE_URL and authenticate via OAuth PKCE-S256 for secure tool discovery and execution.

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

---

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

```yaml

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

```javascript
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`](https://github.com/different-ai/openwork/blob/main/dev/packages/enterprise-mcp-client/src/tool-catalog.ts).

### Skill Manifest Configuration

Define MCP connectivity in your plugin manifest:

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

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

```

This script verifies that references in [`dev/.opencode/skills/shadcn/mcp.md`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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.