Model Context Protocol (MCP)

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:

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

Set up your client

Step-by-step guides for every client:

OpenCode

Claude Code

Codex

Claude Desktop

ChatGPT

Cursor

VS Code

Windsurf

Zed

Gemini CLI

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
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
Cursor	Setup only	Cursor Web/Agents can use an HTTPS OAuth callback. Cursor Desktop OAuth requires `cursor://anysphere.cursor-mcp/oauth/callback`, which OpenWork’s MCP profile intentionally rejects, so Cursor Desktop OAuth is not currently supported.	OpenWork MCP for Cursor
ChatGPT Desktop	Setup only	Setup guide only; use ChatGPT `Settings > MCP servers`. Native proof is not complete.	OpenWork MCP for ChatGPT
Claude Code	Setup only	Setup guide only; native proof is not complete.	OpenWork MCP for Claude Code
Claude Desktop	Setup only	Setup guide only; native proof is not complete.	OpenWork MCP for Claude Desktop
VS Code	Setup only	Setup guide only; native proof is not complete.	OpenWork MCP for VS Code
Windsurf	Setup only	Setup guide only via mcp-remote; native proof is not complete.	OpenWork MCP for Windsurf
Zed	Setup only	Setup guide only via mcp-remote; native proof is not complete.	OpenWork MCP for Zed
Gemini CLI	Setup only	Setup guide only; native proof is not complete.	OpenWork MCP for 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:

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

Then authenticate:

opencode mcp auth openwork

If OpenCode runs on a remote machine but the browser opens locally, follow Connect OpenWork MCP from a remote machine. To reconnect or switch organizations, remove the old token and authenticate again:

opencode mcp logout openwork
opencode mcp auth openwork

Full guide: OpenWork MCP for 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:

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:

codex mcp logout openwork
codex mcp login openwork

Full guide: OpenWork MCP for Codex.

Cursor Web/Agents setup-only guide

Use this guide only for Cursor Web/Agents flows that provide an HTTPS OAuth callback. Paste the OpenWork Connect endpoint where Cursor Web/Agents asks for the remote MCP server URL:

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

Cursor Desktop OAuth is not currently supported. The official desktop OAuth callback is cursor://anysphere.cursor-mcp/oauth/callback, and OpenWork’s MCP profile intentionally rejects private-use callback schemes for public OAuth clients. Full guide: OpenWork MCP for Cursor.

ChatGPT setup-only guide

Open ChatGPT Settings > MCP servers (open settings), paste the OpenWork Connect endpoint, and start OAuth from ChatGPT’s connection prompt:

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

Full guide: OpenWork MCP for 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.

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.

Share with your team

Run in the cloud