OpenClaw

OpenClaw is an MCP client. WorkOS exposes its entire data model through a remote MCP server, so OpenClaw can read and write directly to your workspace — pages, databases, tasks, meetings and sharing.

Connection

The MCP server is at https://workos.no/api/mcp. It uses Streamable HTTP (POST + JSON-RPC 2.0) and OAuth 2.1 with PKCE. Access token lasts one hour, refresh token thirty days.

Important: the server does not open a browser

OpenClaw is a CLI client. The WorkOS server cannot open a browser or pop up an OAuth window on your machine — that's the client's responsibility. OpenClaw must:

1. Build the authorization URL (with PKCE challenge and state).
2. Print the URL to the user — in the terminal, as clickable text — and ask the user to open it manually.
3. Listen on a local port (e.g. http://127.0.0.1:53682/callback) to catch ?code=…&state=… when the user has approved.
4. Exchange the code for an access token and store the token in the configuration.

If OpenClaw just "waits for a browser to appear" without printing a URL, that's a bug in the client. It must generate the link explicitly.

Pseudocode

1. POST https://workos.no/api/oauth/register
   {
     "client_name": "OpenClaw",
     "redirect_uris": ["http://127.0.0.1:53682/callback"],
     "scope": "read write"
   }
   -> { client_id }   // store this. Re-use on every reconnect.

2. verifier  = base64url(random_bytes(64))
   challenge = base64url(sha256(verifier))
   state     = base64url(random_bytes(16))

3. start a one-shot HTTP listener on 127.0.0.1:53682
   (must be running BEFORE you print the URL).

4. PRINT TO USER:
   "Open this URL in your browser to authorize WorkOS:"
   https://workos.no/oauth/authorize
     ?response_type=code
     &client_id=<client_id>
     &redirect_uri=http%3A%2F%2F127.0.0.1%3A53682%2Fcallback
     &code_challenge=<challenge>
     &code_challenge_method=S256
     &scope=read+write
     &state=<state>

5. wait for GET /callback?code=<...>&state=<...>
   verify state matches, then shut the listener down.

6. POST https://workos.no/api/oauth/token  (form-encoded)
   grant_type=authorization_code
   &code=<code>
   &client_id=<client_id>
   &redirect_uri=http://127.0.0.1:53682/callback
   &code_verifier=<verifier>
   -> { access_token, refresh_token, expires_in }

7. POST https://workos.no/api/mcp
   Authorization: Bearer <access_token>
   { JSON-RPC 2.0 payload }

Loopback redirects (http://127.0.0.1:PORT/... and http://localhost:PORT/...) are explicitly allowed during registration — all other redirect_uri must be HTTPS.

When the token has expired

Refresh by POSTing to /api/oauth/token with grant_type=refresh_token, the previous refresh token and client_id. If refresh fails (revoked or older than 30 days), go back to step 3 of the pseudocode — only register again if client_id has been lost.

Common errors

• OpenClaw asks the user for client_id: bug. Use Dynamic Client Registration (step 1) — the user should never see client_id.
• OpenClaw waits for browser: the client must print the authorization URL, not wait for a browser to open.
• 401 after about an hour: the token expired; refresh automatically or run the whole flow again.
• New client_id on every connection: register once, store client_id and refresh_token in the user's config.

More

Full agent guide: /for-agenter (Markdown: /for-agenter.md). Discovery metadata: /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.