---
title: "Model Context Protocol (MCP)"
sidebarTitle: "Overview"
description: "The OpenWork MCP server is a hosted endpoint that lets your AI agent use OpenWork from Claude Code, Codex, Claude Desktop, Cursor, VS Code, or any MCP client."
---

import { OpenWorkConnectInstaller } from "/snippets/openwork-connect-installer.jsx";

The OpenWork Connect MCP server lets your AI agent use the OpenWork capabilities your organization has made available to you. The public hosted endpoint is:

```text
https://api.openworklabs.com/mcp/agent
```

This guide is for connecting an external MCP client to OpenWork. To connect
Gmail, calendar, Drive, Slack, Notion, Linear, or another service inside the
OpenWork desktop app, use
[Connect your services](/start-here/connect-your-stack/connect-services).

Your client opens a browser, you sign in to OpenWork, choose the organization to authorize, and the client stores the OAuth token for that organization.

`app.openworklabs.com/api/den` is an internal same-origin desktop proxy used by OpenWork first-party flows. Do not paste it into external MCP clients.

<OpenWorkConnectInstaller />

## Set up your client

Step-by-step guides for every client:

<CardGroup cols={3}>
  <Card title="OpenCode" href="/model-context-protocol/opencode" />
  <Card title="Claude Code" href="/model-context-protocol/claude-code" />
  <Card title="Codex" href="/model-context-protocol/codex" />
  <Card title="Claude Desktop" href="/model-context-protocol/claude-desktop" />
  <Card title="ChatGPT" href="/model-context-protocol/chatgpt" />
  <Card title="Cursor" href="/model-context-protocol/cursor" />
  <Card title="VS Code" href="/model-context-protocol/vs-code" />
  <Card title="Windsurf" href="/model-context-protocol/windsurf" />
  <Card title="Zed" href="/model-context-protocol/zed" />
  <Card title="Gemini CLI" href="/model-context-protocol/gemini-cli" />
</CardGroup>

## In the OpenWork desktop app

If you use the OpenWork desktop app, there is no MCP endpoint to configure.
When you sign in, the app injects OpenWork Connect with access scoped to your
active organization and refreshes that first-party access automatically. Use
`Settings` > `Connect` to sign in to the services available to you.

## Client support status

| Client | Status | Notes | Guide |
| --- | --- | --- | --- |
| OpenCode | Verified | Native remote MCP OAuth passed end-to-end implementation testing. | [OpenWork MCP for OpenCode](/model-context-protocol/opencode) |
| Codex | Setup only | Add/login/reconnect steps are below; native remote MCP OAuth must be rerun on this exact branch before Codex is marked verified. | [OpenWork MCP for Codex](/model-context-protocol/codex) |
| Cursor | Setup only | Cursor Web/Agents use an HTTPS OAuth callback. Cursor Desktop OAuth uses `cursor://anysphere.cursor-mcp/oauth/callback`, which OpenWork accepts through an exact private-use allowlist with PKCE S256 enforced. Native proof is not complete. | [OpenWork MCP for Cursor](/model-context-protocol/cursor) |
| ChatGPT Desktop | Setup only | Setup guide only; use ChatGPT `Settings > MCP servers`. Native proof is not complete. | [OpenWork MCP for ChatGPT](/model-context-protocol/chatgpt) |
| Claude Code | Setup only | Setup guide only; native proof is not complete. | [OpenWork MCP for Claude Code](/model-context-protocol/claude-code) |
| Claude Desktop | Setup only | Setup guide only; native proof is not complete. | [OpenWork MCP for Claude Desktop](/model-context-protocol/claude-desktop) |
| VS Code | Setup only | Setup guide only; native proof is not complete. | [OpenWork MCP for VS Code](/model-context-protocol/vs-code) |
| Windsurf | Setup only | Setup guide only via mcp-remote; native proof is not complete. | [OpenWork MCP for Windsurf](/model-context-protocol/windsurf) |
| Zed | Setup only | Setup guide only via mcp-remote; native proof is not complete. | [OpenWork MCP for Zed](/model-context-protocol/zed) |
| Gemini CLI | Setup only | Setup guide only; native proof is not complete. | [OpenWork MCP for Gemini CLI](/model-context-protocol/gemini-cli) |
| Any client | Setup only | Use only with clients that support remote Streamable HTTP MCP servers and OAuth. | — |

## OpenCode setup

Add this MCP entry to your OpenCode config:

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

Then authenticate:

```sh
opencode mcp auth openwork
```

If OpenCode runs on a remote machine but the browser opens locally, follow
[Connect OpenWork MCP from a remote machine](/cloud/run-in-the-cloud/connect-openwork-mcp-remote-machine).

To reconnect or switch organizations, remove the old token and authenticate again:

```sh
opencode mcp logout openwork
opencode mcp auth openwork
```

Full guide: [OpenWork MCP for OpenCode](/model-context-protocol/opencode).

## Codex setup

Codex is setup-only for this PR until its native OAuth flow is rerun on this exact branch.

Add OpenWork, then log in:

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

To reconnect or switch organizations, log out and log in again:

```sh
codex mcp logout openwork
codex mcp login openwork
```

Full guide: [OpenWork MCP for Codex](/model-context-protocol/codex).

## Cursor setup-only guide

Paste the OpenWork Connect endpoint where Cursor asks for the remote MCP server URL, then start OAuth from Cursor's connection prompt:

```text
https://api.openworklabs.com/mcp/agent
```

Cursor Web/Agents use an HTTPS OAuth callback. Cursor Desktop OAuth uses the private-use callback `cursor://anysphere.cursor-mcp/oauth/callback`, which OpenWork accepts through an exact allowlist with PKCE S256 enforced, so intercepted authorization codes cannot be redeemed without the code verifier.

Full guide: [OpenWork MCP for Cursor](/model-context-protocol/cursor).

## ChatGPT setup-only guide

Open ChatGPT `Settings > MCP servers` ([open settings](https://chatgpt.com/#settings/Connectors)), paste the OpenWork Connect endpoint, and start OAuth from ChatGPT's connection prompt:

```text
https://api.openworklabs.com/mcp/agent
```

Full guide: [OpenWork MCP for ChatGPT](/model-context-protocol/chatgpt).

## Organization selection

The organization you choose in the browser is pinned into the token. Changing the active organization in OpenWork later does not change an external client's existing token. Use the logout/auth or logout/login reconnect commands above when you need a different organization.

## What you can ask the agent

Once connected, your agent can use OpenWork capabilities from plain English in the composer. These flows are exercised end to end against a live OpenWork Cloud deployment (see `evals/cloud-mcp-agent-flows.md` in the repository):

- **Check your cloud identity** — "Which OpenWork Cloud organization am I
  connected to?" The agent reports the organization, your account, and your
  role.
- **Invite teammates** — "Add omar@example.com to my organization." The agent
  sends the invitation, updates the allowed email domains when needed, and
  surfaces seat-limit billing rules instead of failing silently.
- **Manage teams** — "Assign Priya to the Sales team." Works for active
  members; the agent explains when someone still has a pending invitation.
- **Share skills with your org** — "Create a skill that writes weekly status
  reports and share it with my whole organization." The agent writes the
  `SKILL.md` locally, then creates a plugin, attaches the skill, publishes it
  to your marketplace, and grants org-wide access — teammates see it in their
  marketplace and install it with one click.

Org policy still applies: invitations respect seat limits and domain rules, and resource access follows organization membership, roles, policies, and exposure allowlists.

## OAuth and protocol details

OpenWork Connect is a remote Streamable HTTP MCP server with OAuth:

- The protected resource is exactly `https://api.openworklabs.com/mcp/agent`.
- Clients discover OAuth metadata with RFC9728 protected-resource discovery.
- The authorization server and browser sign-in origin is `https://app.openworklabs.com/api/auth`.
- OAuth authorize and token requests must include exactly one `resource` value: `https://api.openworklabs.com/mcp/agent`.
- Clients that need registration use dynamic client registration as a fallback during discovery.
- PKCE is required for public/dynamic clients, and only the `S256` code challenge method is supported.
- Redirect URIs must be HTTPS callbacks or HTTP loopback callbacks such as `http://127.0.0.1:<port>/callback`. Private-use callback schemes are not accepted for public OAuth clients, except exact allowlisted callbacks for known native clients — currently Cursor Desktop's `cursor://anysphere.cursor-mcp/oauth/callback` — with PKCE S256 enforced.

## Token lifetime and refresh

Clients normally refresh automatically. The values matter when diagnosing reconnects:

- Public OAuth access tokens are JWTs signed and validated with EdDSA. The issuer is exactly `https://app.openworklabs.com/api/auth`, the audience is exactly `https://api.openworklabs.com/mcp/agent`, and access tokens expire after 45 minutes.
- Refresh tokens are opaque rotating grants with a 30-day inactivity window and a 30-second rotation overlap for near-simultaneous refreshes.
- Each refresh revokes the previous refresh grant; because OpenWork stores only token hashes, a replay during the overlap can issue another successor instead of returning prior plaintext.
- Successor grants remain normal rotating grants. If an old refresh grant is replayed after the overlap, expired, or revoked, the client may receive `invalid_grant` and the client/user refresh-token family is revoked. Reconnect by logging out of the MCP entry and authenticating again.
- Access is rechecked against the active OpenWork session and organization membership, so removing a member or revoking the session cuts off MCP access.

## What the server exposes

`/mcp/agent` exposes two MCP tools:

- `search_capabilities` searches the capabilities available to the signed-in member.
- `execute_capability` runs an exact capability name returned by `search_capabilities`.

Search can include OpenWork Cloud resources such as config objects, connectors, plugins, marketplaces, skills, workers, members, roles, teams, model providers, and org-connected external MCP tools when those capabilities are enabled and shared with the member.

Availability is governed by organization membership, role, policy, and exposure allowlists. It intentionally does not expose authentication internals, admin-only system routes, webhooks, API-key creation or deletion, or credential-returning endpoints.

## Troubleshooting

- **401 missing or invalid token**: run the client's auth/login command again. Confirm the client points to `https://api.openworklabs.com/mcp/agent`.
- **403 membership or scope error**: confirm you selected the right organization and still have membership and required permissions there.
- **`invalid_grant`**: the refresh grant was expired, revoked, or replayed after the 30-second rotation overlap. Run logout, then auth/login again.
- **429 rate limit**: wait for the response's `Retry-After` value before retrying.
- **Support requests**: include the response `X-Request-Id` header plus any JSON body MCP `referenceId` or OAuth `reference_id` field so OpenWork support can find the server-side trace.

## Requirements

- An OpenWork Cloud account and organization.
- An MCP client that supports remote Streamable HTTP MCP servers.
- OAuth support in the MCP client, including browser-based authorization.

If your client does not support OAuth for remote MCP servers, it cannot connect to OpenWork Connect yet.
