224 lines
13 KiB
Plaintext
224 lines
13 KiB
Plaintext
---
|
|
title: "OpenWork MCP Gateway"
|
|
sidebarTitle: "Overview"
|
|
description: "The OpenWork MCP Gateway is one hosted endpoint that brings your organization's skills, plugins, and connections into Claude Code, Codex, Claude Desktop, Cursor, VS Code, or any MCP client."
|
|
---
|
|
|
|
import { OpenWorkConnectInstaller } from "/snippets/openwork-connect-installer.jsx";
|
|
|
|
The OpenWork MCP Gateway is one MCP endpoint for everything your organization has made available to you: skills, plugins, workflows, and connections. Instead of configuring one MCP server per service, your agent connects to the gateway once and discovers capabilities on demand. 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:
|
|
|
|
- **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 inside a plugin, adds the plugin to a Collection, and grants the
|
|
Collection org-wide — teammates find the assigned skill in `Settings > Library`.
|
|
|
|
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 gateway exposes
|
|
|
|
Instead of flooding your client with hundreds of tool definitions, the gateway keeps the tool list small and constant. `/mcp/agent` exposes two discovery 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 skills, plugins, connectors, Collections, 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.
|
|
|
|
## MCP Apps
|
|
|
|
Some gateway results come back as MCP Apps: rich, interactive UI rendered from a tool result instead of plain text — great for dynamic interfaces like a created-skill confirmation card or a workflow result view. OpenWork implements the standard [MCP Apps extension](https://modelcontextprotocol.io/docs/extensions/apps) (`ui://` resources declared on tools), so first-party OpenWork apps render in any MCP client that supports the extension, and fall back to readable text everywhere else.
|
|
|
|
<Frame>
|
|
|
|
</Frame>
|
|
|
|
MCP Apps from third-party providers — apps shipped by an MCP server your organization added as a connector — currently render in the OpenWork desktop app, where connectors are enabled as a native MCP Apps preview per organization. Rendering third-party apps in external clients requires exposing that connector as a full MCP server, an option that is planned but not available yet.
|
|
|
|
## 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.
|