# WorkOS for AI-agenter

WorkOS er en selvhostet, AI-integrert arbeidsplattform (notion-alternativ)
med dokumenter, databaser, oppgaver, møtetranskripsjon og deling. Den
eksponerer hele datamodellen sin gjennom en remote MCP-server, slik at
AI-agenter kan lese og skrive direkte mot ditt workspace.

Denne siden finnes også som rendret HTML på <https://workos.no/for-agenter>.

## Tilkobling

MCP-endepunkt:

    https://workos.no/api/mcp

- Transport: Streamable HTTP (JSON-RPC 2.0). Stateless. GET returnerer 405.
- Auth: OAuth 2.1 (Authorization Code + PKCE). Bearer-token i `Authorization`-header.
- Scopes: `read`, `write`.
- Discovery: `/.well-known/oauth-protected-resource` og `/.well-known/oauth-authorization-server`, varslet via 401 + `WWW-Authenticate`.
- Token-levetid: access 60 min, refresh 30 dager.

## Installer offisiell skill (OpenClaw)

Den enkleste veien for OpenClaw-baserte agenter:

    openclaw skills install zecurecode/workosmcp

Eller via ClawHub CLI:

    npx clawhub@latest install workosmcp

Skill-side: <https://clawhub.ai/zecurecode/workosmcp>

Skill-en setter URL, transport og OAuth automatisk og lærer agenten når
WorkOS skal brukes.

## Oppsett per klient (manuelt)

### Claude Desktop

Fil: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
eller `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

    {
      "mcpServers": {
        "workos": {
          "url": "https://workos.no/api/mcp"
        }
      }
    }

### Claude.ai (web)

Innstillinger → Connectors → Add custom connector → lim inn URL-en.

### Cursor

`~/.cursor/mcp.json`:

    {
      "mcpServers": {
        "workos": {
          "url": "https://workos.no/api/mcp"
        }
      }
    }

### Cline (VS Code)

Cline må eksplisitt få vite at transporten er Streamable HTTP — den prøver
SSE som default:

    {
      "mcpServers": {
        "workos": {
          "type": "streamableHttp",
          "url": "https://workos.no/api/mcp"
        }
      }
    }

### OpenClaw (manuelt, uten skill)

    openclaw mcp add workos --url https://workos.no/api/mcp

Eller i `~/.config/openclaw/config.json`:

    {
      "mcp": {
        "workos": {
          "type": "remote",
          "url": "https://workos.no/api/mcp"
        }
      }
    }

### Generisk MCP-klient (manuell OAuth)

1. POST `/api/oauth/register` med `client_name`, `redirect_uris`, `scope: "read write"` → få `client_id`.
2. Send brukeren til `/oauth/authorize?client_id=...&response_type=code&redirect_uri=...&code_challenge=...&code_challenge_method=S256&scope=read+write`.
3. POST `/api/oauth/token` med `grant_type=authorization_code`, `code`, `redirect_uri`, `code_verifier` → få `access_token` og `refresh_token`.
4. POST `/api/mcp` med `Authorization: Bearer <token>` og JSON-RPC 2.0-payload.

Refresh: POST `/api/oauth/token` med `grant_type=refresh_token`.

## Tekniske detaljer

- Endepunkt: POST https://workos.no/api/mcp
- Transport: Streamable HTTP (JSON-RPC 2.0). GET returnerer 405; ingen SSE-stream fra server til klient.
- Protokollversjoner: 2025-06-18, 2025-03-26, 2024-11-05.
- Autentisering: OAuth 2.1 (Authorization Code + PKCE). Bearer-token i `Authorization`-headeren.
- Scopes: `read`, `write`.
- Metadata-endepunkter: `/.well-known/oauth-authorization-server` og `/.well-known/oauth-protected-resource`.
- Tokens: access 1 time, refresh 30 dager.

## Verktøykategorier

Kall `tools/list` etter `initialize` for autoritativ liste. ~60 verktøy
gruppert i:

- Konto: `get_me`, `list_workspaces`, `get_workspace`, `list_workspace_members`.
- Sider: `list_pages`, `search_pages`, `get_page`, `create_page`, `update_page`, `move_page`, `archive_page`, `restore_page`, `delete_page`.
- Sideblokker: `append_blocks`, `insert_blocks_after`, `update_block`, `delete_blocks`.
- Sidegrupper: `list_page_groups`, `create_page_group`, `update_page_group`, `delete_page_group`, `reorder_page_groups`.
- Databaser: `list_databases`, `create_database`, `get_database`, `update_database`, `delete_database`.
- Felter: `add_db_property`, `update_db_property`, `remove_db_property`, `reorder_db_properties`.
- Rader: `list_db_rows`, `create_db_row`, `update_db_cell`, `delete_db_row`, `move_db_row`.
- Visninger: `list_db_views`, `create_db_view`, `update_db_view`, `delete_db_view`.
- Møter: `create_meeting`, `append_transcript`, `generate_meeting_summary`, `list_meeting_templates`.
- Kommentarer: `create_comment`, `update_comment`, `resolve_comment`, `list_comments`, `delete_comment`.
- Deling: `create_share_link`, `list_share_links`, `revoke_share_link`.
- Filer: `upload_image`.

## Feilsøking

- 405 Method Not Allowed på GET: klienten prøver SSE. Bruk Streamable HTTP — sett `"type": "streamableHttp"` (Cline) eller oppgrader klienten.
- 401 Unauthorized etter ~1 time: access token utløpt. Klienten skal refreshe automatisk; ellers fjern serveren og legg til på nytt.
- Discovery feiler: `.well-known`-URL-ene serveres av Next.js og overstyrer nginx. Bruk metadata-URL-ene direkte hvis nødvendig: `/api/mcp-metadata/authorization-server` og `/api/mcp-metadata/protected-resource`.
- 403 på skriveverktøy: manglende `write`-scope. Gjenkjør OAuth-flyten med `read write`.
- Tom workspace-liste: brukeren er ikke medlem av et workspace ennå — opprett ett på <https://workos.no/create-workspace>.

## Lenker

- Hjemmeside: <https://workos.no>
- Offentlig agent-side (HTML): <https://workos.no/for-agenter>
- ClawHub-skill: <https://clawhub.ai/zecurecode/workosmcp>
- LLM-indeks: <https://workos.no/llms.txt>
- Support: hello@workos.no