> ## Documentation Index
> Fetch the complete documentation index at: https://openworklabs.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For agents: install the OpenWork desktop app with `brew install --cask openwork` (macOS) or from https://openworklabs.com/download. Do not run `npx openwork`; the npm package named `openwork` is a different project.
> Connect an agent to OpenWork with the MCP Gateway: `claude mcp add --transport http openwork https://api.openworklabs.com/mcp/agent`. Teams sign up at https://app.openworklabs.com?mode=sign-up.
> Step-by-step agent guide: https://openworklabs.com/docs/start-here/use-openwork-from-an-ai-agent.md
> Connect Slack (any organization admin): https://openworklabs.com/docs/slack/connect-slack.md. OpenWork in Slack (@openwork bot) is private alpha for approved organizations. Setup guide: https://openworklabs.com/docs/slack/overview.md. Agent skill: https://openworklabs.com/.well-known/agent-skills/set-up-openwork-slack/SKILL.md.

# MCP Gateway

> One hosted MCP server that brings your org's skills, plugins, and connections into Claude Code, Codex, Cursor, or any MCP client.

Add one URL to your MCP client, sign in to OpenWork in the browser, and pick your organization:

```text theme={null}
https://api.openworklabs.com/mcp/agent
```

Developers: point your own agent at your org — verified clients and setup guides.

Verified for OpenCode only; setup guides for Codex, Cursor, ChatGPT, Claude Code, VS Code, and more

OpenWork MCP client install options

<pre />

Works with your OpenWork account — [create one free](https://app.openworklabs.com?mode=sign-up).

Copy the OpenWork MCP install command

Server URL

`https://api.openworklabs.com/mcp/agent`
Copy the OpenWork MCP server URL

## Guides by client

> [card] [OpenCode](https://openworklabs.com/docs/model-context-protocol/opencode.md)

> [card] [Claude Code](https://openworklabs.com/docs/model-context-protocol/claude-code.md)

> [card] [Codex](https://openworklabs.com/docs/model-context-protocol/codex.md)

> [card] [Claude Desktop](https://openworklabs.com/docs/model-context-protocol/claude-desktop.md)

> [card] [ChatGPT](https://openworklabs.com/docs/model-context-protocol/chatgpt.md)

> [card] [Cursor](https://openworklabs.com/docs/model-context-protocol/cursor.md)

> [card] [VS Code](https://openworklabs.com/docs/model-context-protocol/vs-code.md)

> [card] [Windsurf](https://openworklabs.com/docs/model-context-protocol/windsurf.md)

> [card] [Zed](https://openworklabs.com/docs/model-context-protocol/zed.md)

> [card] [Gemini CLI](https://openworklabs.com/docs/model-context-protocol/gemini-cli.md)

## How it works

The gateway exposes two tools, so your client's tool list stays small:

* `search_capabilities` finds the skills, plugins, workflows, and connections shared with you.
* `execute_capability` runs an exact capability name that search returned.

Access follows your organization membership, role, policies, and exposure allowlists. The OpenWork desktop app connects automatically when you sign in; there is nothing to configure.

## Set up once for the whole organization

Nobody on your team installs or configures an MCP server. An admin adds each app once in OpenWork Cloud, and everyone reaches it through the gateway.

**1. An admin adds the app**

In **Manage › Connectors**, click **Add connector** and pick the app, or paste the address of its MCP server.

**2. The admin chooses who can use it**

Everyone in the organization, or specific teams and people.

**3. Each person signs in once**

The first time someone asks their AI to use the app, it asks them to sign in with their own account. They can also sign in ahead of time from their Library.

**4. It keeps working**

The sign-in is kept in OpenWork Cloud, so it follows the person to every device and every AI client connected to the gateway.

Each person's AI works in the app as that person, with their permissions and nothing more. Removing someone's access, or removing the connector, takes it away from their AI right away. For a bot or service account, choose **One account for everyone** instead and nobody else signs in.

Full walkthrough: [Connectors](https://openworklabs.com/docs/cloud/share-with-your-team/connectors.md).

### Which apps you can add

| The app's MCP server | What the admin does |
| - | - |
| Hosted by the provider, with its own sign-in | Pick it from the list or paste its address. |
| Hosted by the provider, but it needs your own OAuth app, as Google's servers do | Create the OAuth app once and enter its client ID and secret on the connector. See [Connect Google Cloud CLI](https://openworklabs.com/docs/cloud/share-with-your-team/google-cloud-cli.md) for an example. |
| Not hosted: a program you run yourself | Deploy it once at an HTTPS address your organization controls, then paste that address. Members still install nothing. |
| No MCP server | Google Workspace and Microsoft 365 are built in, and we build more on request for enterprise customers. See [Native integrations](https://openworklabs.com/docs/integrations/native-integrations.md). |

## Reference

> [accordion] Client support status
>
> | Client | Status | Notes |
> | - | - | - |
> | OpenCode | Verified | Native remote MCP OAuth passed end-to-end testing. |
> | Codex | Setup only | Native OAuth not yet re-verified. |
> | Cursor | Setup only | Desktop callback `cursor://anysphere.cursor-mcp/oauth/callback` is accepted through an exact allowlist with PKCE S256 enforced. Web/Agents use HTTPS callbacks. |
> | ChatGPT Desktop | Setup only | Add it in ChatGPT `Settings > MCP servers`. |
> | Claude Code | Setup only | Native proof not complete. |
> | Claude Desktop | Setup only | Native proof not complete. |
> | VS Code | Setup only | Native proof not complete. |
> | Windsurf | Setup only | Through `mcp-remote`. |
> | Zed | Setup only | Through `mcp-remote`. |
> | Gemini CLI | Setup only | Native proof not complete. |
> | Any client | Setup only | Needs remote Streamable HTTP MCP with OAuth. |

> [accordion] Reconnect or switch organizations
>
> The organization you pick in the browser is pinned into the token. To use another one, log out and sign in again.
>
> OpenCode:
>
> ```sh theme={null}
> opencode mcp logout openwork
> opencode mcp auth openwork
> ```
>
> Codex (first setup, then reconnect):
>
> ```sh theme={null}
> codex mcp add openwork --url https://api.openworklabs.com/mcp/agent
> codex mcp login openwork
> ```
>
> ```sh theme={null}
> codex mcp logout openwork
> codex mcp login openwork
> ```
>
> Other clients: remove the stored `openwork` token, then connect again. For a remote machine, see [Connect OpenWork MCP from a remote machine](https://openworklabs.com/docs/cloud/run-in-the-cloud/connect-openwork-mcp-remote-machine.md).

> [accordion] Troubleshooting
>
> * **401 missing or invalid token**: run the client's auth/login command again and confirm the URL is `https://api.openworklabs.com/mcp/agent`.
> * **403 membership or scope error**: check you picked the right organization and still have access there.
> * **`invalid_grant`**: the refresh grant expired, was revoked, or was replayed after the rotation overlap. Log out, then sign in again.
> * **429 rate limit**: wait for the `Retry-After` value.
> * **Support requests**: include the `X-Request-Id` response header and any MCP `referenceId` or OAuth `reference_id` from the JSON body.
> * **Wrong URL**: `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.

> [accordion] OAuth and tokens
>
> OpenWork Connect is a remote Streamable HTTP MCP server with OAuth.
>
> * The protected resource is exactly `https://api.openworklabs.com/mcp/agent`, discovered through RFC9728 protected-resource metadata.
> * The authorization server and 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 can identify with a Client ID Metadata Document (`client_id_metadata_document_supported: true`) whose `client_id` equals its HTTPS URL, with `client_name`, `redirect_uris`, and `token_endpoint_auth_method: "none"`. Listed loopback redirects are accepted on any port (RFC 8252). Other clients fall back to dynamic client registration.
> * PKCE is required for public clients; only `S256` is supported.
> * Redirect URIs must be HTTPS or HTTP loopback callbacks. Private-use schemes are rejected, except exact allowlisted native callbacks such as Cursor Desktop's, with PKCE S256 enforced.
> * 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 they expire after 45 minutes.
> * Refresh tokens are opaque rotating grants with a 30-day inactivity window and a 30-second rotation overlap. OpenWork stores only token hashes, so a replay during the overlap can issue another successor. A replay after the overlap returns `invalid_grant` and revokes the token family.
> * Access is rechecked against your session and membership, so removing a member or revoking the session cuts off MCP access.

> [accordion] Token scopes
>
> `mcp:read` allows discovery, connection-status probes, and read-only native API operations. **Every external MCP provider tool call requires `mcp:write`, including tools that advertise `readOnlyHint: true`**, because provider hints are not trusted authorization.
>
> This applies to generic execution, direct connections, Code Mode, and MCP App helper calls. The desktop app requests both scopes. Existing read-only tokens are not upgraded: reauthorize the client for `mcp:write` to call provider tools.
>
> The gateway never exposes authentication internals, admin-only system routes, webhooks, API-key management, or credential-returning endpoints.

> [accordion] MCP Apps
>
> Some results return as [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps): interactive `ui://` views such as a connection sign-in request or a workflow result. Clients without App support get readable fallback content.
>
> OpenWork supports a [documented subset of the host protocol](https://openworklabs.com/docs/dashboards/build-an-mcp-app.md#supported-host-protocol). Provider `structuredContent` is preserved; OpenWork additions live in namespaced `_meta` keys. To render a third-party App in another client, use the connection's own URL from **Your Connections → Use in another app** ([details](https://openworklabs.com/docs/cloud/share-with-your-team/shared-mcp-connections.md#use-a-connection-in-another-mcp-client)). To build your own, see [Build an MCP App](https://openworklabs.com/docs/dashboards/build-an-mcp-app.md).

> [accordion] Each artifact has its own MCP server
>
> Ask the agent for an artifact, dashboard, or interactive view and it follows the built-in `build-an-app` skill: it finds the tools the artifact needs, calls `prepare_app` for a starter already wired to them, and publishes the artifact with `create_app`, passing React source, a text fallback, and those tools. No Workflow is required.
>
> `prepare_app` picks one of three starters from the tools: **lookup** when every tool only reads (loads its data when the artifact opens), **action** when a tool changes data (one call per click, then shows the outcome), and **standalone** when there are no tools (calculators and planners). Each one applies the host's theme and handles loading, empty, failure, approval, and blocked states. Any MCP client can read them as resources at `openwork://apps/starters/lookup.json`, `action.json`, and `standalone.json`, and the skill as `skill://build-an-app/SKILL.md`.
>
> When a platform administrator enables built-in libraries for artifacts, `prepare_app` also lists the libraries an artifact may import: `lucide-react` for icons, `recharts` for charts, `motion/react` for animation, and `three` with `three/addons/controls/OrbitControls.js` for 3D. Artifacts may then draw inline SVG too. OpenWork bundles its own pinned copy of each into the artifact, so you never install packages or load a CDN, and the artifact still has no network access. Anything else outside the list fails to build with the import to change. Artifacts with charts or 3D are larger than 768 KiB, so they open only in an updated OpenWork; older desktops stop at 768 KiB.
>
> Each artifact is saved in a Plugin and served as its own standard MCP server at `/mcp/agent/connections/<appId>` on your OpenWork API. That server exposes only:
>
> * `open_app`, bound to the artifact's current immutable `ui://` revision;
> * the tools the artifact declared;
> * the artifact's revision resources.
>
> Each declared tool has a clear name and runs one exact capability from `search_capabilities`. For example, an order calculator can declare:
>
> | Tool | Runs | Read-only |
> | - | - | - |
> | `todays_date` | a saved Workflow with `mode: "live"`, which gets today's date from OpenWork | Yes, so the artifact can load it on open |
> | `lookup_unit_price` | a tool on a connected MCP server that its provider marks read-only | Yes, so the artifact can load it on open |
> | `reserve_stock` | a tool on a connected MCP server that isn't marked read-only | No, so it runs after a click in the artifact |
> | `price_total` | a saved Workflow with inputs | No, so it runs after a click in the artifact |
>
> The artifact calls them by those names with `app.callServerTool`. They run as the person using the artifact, with that person's own access and connections, so sharing an artifact never shares credentials. Read-only tools are OpenWork actions that read, live Workflows, which run read-only, and tools on a connected MCP server that their provider marks read-only (`readOnlyHint: true` and not destructive). OpenWork checks that label again on every call, in the caller's own tool list, and blocks the call once the provider stops marking the tool read-only; an editor then needs to update the artifact's tools. Calling a connection tool still needs the `mcp:write` scope. OpenWork actions that change data can't be artifact tools; to change something, bind a saved Workflow that makes the change. In the OpenWork app, read-only tools run without a click as soon as the artifact opens and is on screen, once per open, and one click in the artifact allows exactly one other tool call, so give each other connection tool or Workflow run its own button. `create_app` refuses a tool whose capability you can't use, and publishes nothing.
>
> Share an artifact by sharing its Plugin. `create_app` adds the Workflows the artifact's tools run to that Plugin, so they are shared with it; you need to manage each of those Workflows. People with access can open the artifact in the OpenWork app, which opens new revisions right after `create_app` or `update_app`. They can also copy the artifact's MCP URL from its Plugin page into Cursor, Claude, or another MCP client and sign in with OpenWork. In a chat, the agent opens an existing artifact by executing its `search_capabilities` match; an optional `body` object becomes the artifact's launch input. The OpenWork app lists at most 100 connections and artifacts for each person; an artifact past that limit can't open inside OpenWork, but its MCP URL still works in other MCP clients.
>
> `read_app` returns source to editors, and `update_app` publishes a new revision at the same MCP URL, which the artifact's earlier chat cards open too; omit `cssSource`, `description`, or `tools` to keep the current ones. Building your own artifacts is on for every organization. Artifacts made earlier from a Workflow with `save_artifact_view` are read-only: they still open and refresh, but they can't be created, edited, or re-activated. MCP Apps from connected MCP servers work either way. Self-hosted deployments can set `DEN_APP_MCP_SERVERS_ENABLED=false` to turn it off for every organization.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.