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

​
Guides by client

OpenCode

Claude Code

Codex

Claude Desktop

ChatGPT

Cursor

VS Code

Windsurf

Zed

Gemini CLI

​
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.

​
Reference

The organization you pick in the browser is pinned into the token. To use another one, log out and sign in again.OpenCode:
Codex (first setup, then reconnect):
Other clients: remove the stored openwork token, then connect again. For a remote machine, see Connect OpenWork MCP from a remote machine.
  • 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.
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.
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.
Some results return as MCP 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. 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). To pin one to a dashboard, see Dashboards.
Ask the agent for an app, dashboard, or interactive view and it calls create_app with React source, a text fallback, and the tools the App needs. No Workflow is required. Each App 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 App’s current immutable ui:// revision;
  • the tools the App declared;
  • the App’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:The App calls them by those names with app.callServerTool. They run as the person using the App, with that person’s own access and connections, so sharing an App 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 App’s tools. Calling a connection tool still needs the mcp:write scope. OpenWork actions that change data can’t be App tools; to change something, bind a saved Workflow that makes the change. In the OpenWork app, read-only tools can run as soon as the App opens, and one click in the App 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 App by sharing its Plugin. create_app adds the Workflows the App’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 App in the OpenWork app, which opens new revisions right after create_app or update_app. They can also copy the App’s MCP URL from its Plugin page into Cursor, Claude, or another MCP client and sign in with OpenWork. Admins can put an App on an organization dashboard from Add app → Apps built in OpenWork; its tile keeps opening the App’s latest revision. In a chat, the agent opens an existing App by executing its search_capabilities match; an optional body object becomes the App’s launch input. The OpenWork app lists at most 100 connections and Apps for each person; an App 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 App’s earlier chat cards open too; omit cssSource, description, or tools to keep the current ones. Building your own Apps is off by default: an OpenWork platform admin turns it on for an organization in /admin, and it also needs member-facing MCP connections, which are on by default. Once it is on, Apps 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.