> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# monday.com
> Let Agent Factory agents manage monday.com boards, items, docs and users through MCP, with per-user OAuth resolved server-side or a workspace API token
The monday.com connector wraps the [monday.com](https://monday.com) v2 GraphQL API as MCP tools for **Agent Factory** agents, and as `Monday.op:` App instructions for Builder automations — covering boards, items, subitems, columns, groups, workspaces, updates, files, webhooks, docs, folders, tags and activity logs, plus a generic `graphql` passthrough. The MCP server runs in the **tenant app-instance context**: it resolves the installing workspace's own credentials and authorizes the calling agent against that workspace's allowlist. Authentication supports three modes:
* **Per-user OAuth2 — central client** (`oauthCentral`, recommended) — one monday.com OAuth application is registered once by the platform maintainer; every end user signs in with their own monday.com account. Nothing to register per workspace: each one just installs the app and clicks *Connect*.
* **Per-user OAuth2 — tenant client** (`oauth`) — paste your own monday.com OAuth client ID/secret in the connector config app. Each user signs in with their own account against your client (authorization-code + PKCE flow).
* **Personal API Token** (`accessToken`) — a caller-managed monday.com Personal API Token (v2), used as-is with no exchange. One identity acts for the whole workspace.
Boards, items, subitems, columns and groups with full CRUD, plus cursor pagination and column-value filtering.
Updates, in-app notifications, webhooks, tags, docs, users and teams.
Per-user OAuth (central or tenant client) resolved server-side, or a workspace Personal API Token.
## Who is this for?
This connector is used by three different roles. Jump to the section that matches yours — each one is self-contained.
You build agents in **Agent Factory** and want them to use monday.com. → *Agent builder* tab.
You run the platform and set up the shared monday.com OAuth client once for everyone. → *Platform admin setup* accordion below.
You write Builder automations (DSUL) that call monday.com operations directly. → *Workspace builder* tab.
## Prerequisites
* A **monday.com** account.
* For the **OAuth modes** — a **monday.com OAuth application** created at [monday.com/developers/apps](https://monday.com/developers/apps); copy its **Application ID** (client id) and **Client Secret**. The platform maintainer registers one app for the central mode; a workspace can also register its own for the tenant mode.
* For the **access-token mode** — a **Personal API Token (v2)** generated in *monday.com Developer center > My access tokens*.
* The default OAuth scopes requested are:
```text theme={null}
boards:read boards:write docs:read docs:write updates:read updates:write users:read users:write workspaces:read workspaces:write webhooks:read webhooks:write assets:read notifications:write me:read account:read teams:read tags:read
```
* Base URL: `https://api.monday.com` (the connector targets the `/v2` GraphQL endpoint).
**Goal:** two one-time tasks — (1) configure the shared **central OAuth client** so every workspace lets its users sign in with their own monday.com account, and (2) optionally expose monday.com as a reusable **capability** in AI Governance so agent builders can pick it without pasting endpoint URLs. Throughout, `` is your environment's API URL (`https://api.studio.prisme.ai/v2` on production).
## 1. Configure the connector
Open [monday.com/developers/apps](https://monday.com/developers/apps) and create an OAuth application. Set the single authorized redirect URI (callback URL) to the **core workspace** callback:
```text theme={null}
/workspaces/slug:monday/webhooks/oauthCallback
```
(e.g. `https://api.studio.prisme.ai/v2/workspaces/slug:monday/webhooks/oauthCallback` on production). Add the scopes listed in *Prerequisites*. Save and copy the **Application ID** (client id) and **Client Secret** (the secret is shown only once).
Open the central `monday` workspace and launch its **Configuration app** — `/apps/monday` (e.g. `https://studio.prisme.ai/apps/monday`). Loaded from the core workspace, the app shows the **maintainer view** (org owner / editor / admin only); paste the **Application ID** and **Client Secret** there and Save — the app stores them in the core workspace's secrets for you. Do not edit Studio's raw Secrets by hand. These credentials stay in the `monday` workspace and are never exposed to tenants or end users; token exchange is proxied through the core `centralTokenExchange` webhook so the client secret never leaves the core workspace.
Each consuming workspace selects auth mode **`oauthCentral`** in the connector configuration app (no client id/secret to enter on their side). Their users then just click **Connect**.
From that same maintainer view, the **Add to catalog** button publishes monday.com to the org-wide **Capabilities catalog** in one click (org owner / admin only; it stays disabled until the central client is saved). Once published, every agent builder in the org can enable monday.com from the catalog without pasting an endpoint — see *Option A* in the *Agent builder* tab.
## 2. Declare the capability in AI Governance
As an alternative to (or in addition to) the catalog button, you can declare monday.com as a named **capability** in AI Governance. Agent builders then enable that capability on their agents instead of pasting a raw MCP endpoint.
Create (or edit) the **monday.com** capability.
Set the capability's MCP server URL to the connector's **MCP Endpoint**, and set its **Scope** to:
```text theme={null}
context_id,agent_id,user_id
```
The `agent_id` in the scope is what lets the connector identify and authorize the calling agent.
Once created, the capability appears in the capability picker for agent builders in your organization, who enable it on their agents. Access to the catalog follows your organization's existing roles; there is no per-capability role grant.
From an agent that has the capability, in a workspace configured for `oauthCentral`, trigger any tool (e.g. `me`). The user is prompted to connect once (monday.com sign-in); subsequent calls reuse the stored token transparently and refresh it automatically.
Declaring the capability makes the connector **available**; it does not by itself authorize a specific agent. This connector follows the **tenant-context model** — which agents may actually call it is gated per-workspace by the **authorized-agents allowlist** in the configuration app (see the *Workspace builder* tab). There is also **no OAuth auth-config JSON** to attach in Governance: connect / status / disconnect are handled by the connector's own webhooks, wired automatically.
***
## Agent builder
**Goal:** let an agent you build in Agent Factory use monday.com through MCP tools.
Before an agent can call the connector, a *Workspace builder* must have installed and configured the monday.com app in a workspace (see the *Workspace builder* tab), and — for the central OAuth mode — a *Platform admin* must have provisioned the shared OAuth client (see the *Platform admin setup* accordion above).
This connector runs in the **tenant app-instance context**: your agent is authorized two ways at once — it is identified by the `agent_id` that Agent Factory injects through the capability *Scope*, and that agent must appear in the connector's **authorized-agents allowlist** (managed in the configuration app). The monday.com access token itself is resolved server-side from the configured auth mode.
There are two ways to wire it up. Pick based on how much isolation you need.
## Option A — Enable the shared capability from the catalog
The fastest path: a *Platform admin* has already published a **monday.com** capability to the Capabilities catalog (see the *Platform admin setup* accordion above — the **Add to catalog** button, or §2), so you just pick it from the catalog.
Open the agent you want to extend and go to its capabilities / tools.
Browse the capability catalog, select **monday.com**, and enable it. The MCP endpoint URL and the *Scope* (`context_id,agent_id,user_id`) are already wired by the admin — nothing to paste, and the shared instance accepts every agent, so there is no allowlist step on your side.
On the first tool call, an unconnected user is prompted to sign in — Agent Factory surfaces a `connect_url` to monday.com's authorization page. After sign-in the per-user token is stored and reused on subsequent calls.
Convenient, but your agent runs against a **shared, platform-managed instance**: its monday.com credentials are owned by someone else and the instance accepts every agent that is granted the capability. Prefer Option B for anything beyond quick experiments.
## Option B — Run it from your own workspace (recommended)
For production agents, install the connector in **your own workspace** and point the agent at *that* workspace's MCP endpoint.
**Prefer this mode for security.** Because the MCP runs in *your* app-instance context, the monday.com credentials, the per-user OAuth tokens and the authorized-agents allowlist are all **scoped to your workspace** — not shared platform-wide. You decide exactly which agents may call it and which monday.com account / auth mode backs them, and a misconfiguration elsewhere can never expose your data. The shared catalog capability (Option A) is a broad surface many agents can reach; your own workspace is an isolated, least-privilege boundary.
Follow the *Workspace builder* tab: install **monday.com** in your workspace, open its **Configuration app**, choose the auth mode and connect a monday.com account (or paste a Personal API Token).
In that workspace's config app, open **Authorized agents** and tick your agent (the **Install capability** button does this for you), or enable **Allow all agents**.
In your agent, add a capability pointing at **your workspace's MCP Endpoint** URL, and set its **Scope** to:
```text theme={null}
context_id,agent_id,user_id
```
The `agent_id` is what lets the connector identify and authorize your agent — without it, every call is rejected with an explicit "agent could not be identified" message. This *Scope* is separate from the monday.com OAuth scopes.
On the first tool call, the user is prompted to sign in (or uses **Connect** in the config app). The per-user token is stored and reused; refresh is automatic.
## Brief the agent in its system prompt
Whichever option you pick, wiring the capability is not enough — the agent also needs to know the tools exist and when to reach for them. Copy-pasteable starter:
```text theme={null}
You have access to the monday.com MCP server. Use it whenever the user asks about monday.com content — boards, groups, items, sub-items, columns (status, person, date, …), updates, docs or users. Examples: "List the items in the Sprint board grouped by status", "Add an update to the Marketing campaign item", "Move this item to Done", "Create a new task assigned to Alice". monday.com IDs are numeric strings, so list the parent (boards, then columns/groups/items) before acting on it rather than guessing IDs. Confirm with the user before any destructive action (delete an item, archive a board, change ownership).
```
**Legacy AI Knowledge agents** (no native MCP picker): add the connector under **Advanced > Tools > MCP** and paste the **MCP Endpoint** URL. The agent still has to be allowlisted in the config app and its identity propagated so the connector can read its `agent_id`.
**Restricting to read-only (least privilege).** monday.com tools cover both reads and writes (create/update boards, items, docs). The requested OAuth scopes **are** the grant. To allow only read access, set the **Scopes** field in the configuration app to the read-only set, dropping every `:write` scope, e.g.:
```text theme={null}
boards:read docs:read updates:read users:read workspaces:read assets:read me:read account:read teams:read tags:read
```
With central OAuth (`oauthCentral`) you do **not** create your own monday app — keep `oauthCentral` and enter the read scopes; your tenant scope overrides the platform default (the central app must list these read scopes). Write calls (GraphQL mutations) are then rejected by monday with a permission error. The scope is set at the workspace level (a workspace editor can widen it again).
## Available Tools
All tools accept an `outputFormat` argument (`verbose` default / `structured` / `both`). monday.com IDs are numeric strings; list the parent resource first to obtain them.
### Boards
| Tool | Description |
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `boards` | List boards (optional filters by ids / workspace / state) |
| `get_board` | Get a single board with its groups, columns and paged items |
| `create_board` / `update_board` / `duplicate_board` / `archive_board` / `delete_board` | Full board lifecycle |
### Items & Subitems
| Tool | Description |
| ----------------------------------------------------- | ---------------------------------------------------------------------- |
| `items_page` | Cursor-paginated items of one or more boards (optional `query_params`) |
| `items_page_by_column_values` | Paginated items filtered by column values |
| `get_items` | Fetch up to 100 items by ID |
| `create_item` / `create_subitem` / `duplicate_item` | Create or clone items |
| `move_item_to_group` / `move_item_to_board` | Relocate items |
| `archive_item` / `delete_item` / `clear_item_updates` | Archive, delete, or clear updates |
### Columns
| Tool | Description |
| ------------------------------------------------------------------ | ----------------------------------------------- |
| `columns` | List columns (with types and JSON settings) |
| `create_column` | Create any of 37 column types |
| `change_column_title` / `change_column_metadata` / `delete_column` | Rename, edit metadata or delete columns |
| `change_column_value` | Update a single value with a typed JSON payload |
| `change_simple_column_value` | Update a value with a simple string |
| `change_multiple_column_values` | Bulk-update several columns in one call |
### Groups
| Tool | Description |
| -------------------------------------------------------------------------------------- | --------------------------------- |
| `groups` | List groups of one or more boards |
| `create_group` / `update_group` / `duplicate_group` / `archive_group` / `delete_group` | Group lifecycle |
### Users & Teams
| Tool | Description |
| ---------------------------------------------- | ------------------------------------------ |
| `users` | List users (filter by kind / email / name) |
| `me` | Get the user whose token is used |
| `invite_users` / `deactivate_users` | Manage user lifecycle |
| `teams` | List teams |
| `add_users_to_team` / `remove_users_from_team` | Manage team membership |
### Workspaces
| Tool | Description |
| ------------------------------------------------------------ | ----------------------------- |
| `workspaces` | List workspaces |
| `create_workspace` / `update_workspace` / `delete_workspace` | Workspace lifecycle |
| `add_users_to_workspace` / `delete_users_from_workspace` | Manage subscribers and owners |
### Updates (comments)
| Tool | Description |
| ------------------------------------------------- | -------------------- |
| `updates` / `item_updates` | List updates |
| `create_update` / `edit_update` / `delete_update` | Manage updates |
| `pin_to_top` / `unpin_from_top` | Pin or unpin updates |
| `like_update` / `unlike_update` | React to updates |
### Tags, Assets, Webhooks, Notifications
| Tool | Description |
| ------------------------------------------------ | ------------------------------------- |
| `tags` / `board_tags` / `create_or_get_tag` | Browse and create tags |
| `assets` | Fetch file assets by ID |
| `webhooks` / `create_webhook` / `delete_webhook` | Manage board webhooks |
| `create_notification` | Send an in-app notification to a user |
### Docs & Folders
| Tool | Description |
| --------------------------------------------------------------- | ---------------------------------------------------------- |
| `docs` / `doc_blocks` | List docs and blocks |
| `create_doc` | Create a doc in a workspace or attach it to an item column |
| `create_doc_block` / `update_doc_block` / `delete_doc_block` | Manage doc blocks (17 block types) |
| `folders` / `create_folder` / `update_folder` / `delete_folder` | Manage folders in a workspace |
### Meta & Admin
| Tool | Description |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `activity_logs` | Activity log of boards, filtered by time or user |
| `board_views` | Views configured on a board |
| `account` / `account_products` | Account info and installed products |
| `complexity` | Remaining per-minute complexity budget |
| `version` | API version currently served |
| `graphql` | Run a raw monday.com GraphQL `query` with `variables` — the escape hatch for endpoints not covered by a dedicated tool |
## Output Formats
Every tool accepts an `outputFormat` parameter that controls the MCP response shape:
* **`verbose`** (default) — human-readable text optimized for LLM consumption.
* **`structured`** — machine-readable JSON in `structuredContent`.
* **`both`** — both text and structured content.
## Tool Details
### create\_item
```json theme={null}
{
"name": "create_item",
"arguments": {
"board_id": "1234567890",
"item_name": "Ship onboarding revamp",
"group_id": "topics",
"column_values": {
"status": { "label": "Working on it" },
"date": { "date": "2026-05-15" }
},
"create_labels_if_missing": true
}
}
```
| Parameter | Required | Description |
| -------------------------- | -------- | ------------------------------------------------------------------------- |
| `board_id` | Yes | Existing board ID (numeric string). Call `boards` first. |
| `item_name` | Yes | Name of the new item. |
| `group_id` | No | Target group ID (call `groups` first). |
| `column_values` | No | Map of `column_id → value`; the payload shape depends on the column type. |
| `create_labels_if_missing` | No | Auto-create missing `status` / `dropdown` labels. |
### items\_page\_by\_column\_values
Filter board items by column values server-side.
```json theme={null}
{
"name": "items_page_by_column_values",
"arguments": {
"board_id": "1234567890",
"columns": [
{ "column_id": "status", "column_values": ["Done"] },
{ "column_id": "person", "column_values": ["alice@example.com"] }
],
"limit": 50
}
}
```
| Parameter | Required | Description |
| ---------- | -------- | ------------------------------------------------ |
| `board_id` | Yes | Board to query. |
| `columns` | Yes | Array of `{ column_id, column_values }` filters. |
| `cursor` | No | Pagination cursor from a previous page. |
| `limit` | No | Page size (default 25). |
### change\_column\_value vs change\_simple\_column\_value
* `change_column_value` takes a **typed JSON payload** (e.g. `{"label": "Done"}` for `status`, `{"date": "2026-05-15"}` for `date`).
* `change_simple_column_value` takes a **plain string** and lets monday.com infer the format (e.g. `Done`, `2026-05-15`).
Use the typed variant when you need precise control (e.g. a people column with `{"personsAndTeams":[{"id":123,"kind":"person"}]}`).
```json theme={null}
{
"name": "change_simple_column_value",
"arguments": {
"board_id": "1234567890",
"item_id": "9876543210",
"column_id": "status",
"value": "Done"
}
}
```
| Parameter | Required | Description |
| -------------------------- | -------- | ----------------------------------------------------------- |
| `board_id` | Yes | Board the item belongs to. |
| `column_id` | Yes | Column to update. |
| `value` | Yes | Simple string value (typed JSON for `change_column_value`). |
| `item_id` | No | Target item ID. |
| `create_labels_if_missing` | No | Auto-create missing labels. |
### create\_notification
```json theme={null}
{
"name": "create_notification",
"arguments": {
"user_id": "987",
"target_id": "1234567890",
"text": "Staging is ready for review",
"target_type": "Project"
}
}
```
| Parameter | Required | Description |
| ------------- | -------- | ----------------------------------------------- |
| `user_id` | Yes | Recipient user ID (call `users` first). |
| `target_id` | Yes | Item or board ID the notification points to. |
| `text` | Yes | Notification text. |
| `target_type` | Yes | `Project` for boards/items, `Post` for updates. |
### create\_doc
```json theme={null}
{
"name": "create_doc",
"arguments": {
"location": {
"workspace": {
"workspace_id": "42",
"name": "Release Notes",
"kind": "private",
"folder_id": "99"
}
}
}
}
```
To attach a doc to a board item, use `location.board` instead:
```json theme={null}
{ "location": { "board": { "item_id": "1234567890", "column_id": "doc_column" } } }
```
| Parameter | Required | Description |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `location` | Yes | Must contain exactly one of `workspace` (requires `workspace_id`, `name`, `kind`) or `board` (requires `item_id`, `column_id`). |
## Workspace builder
**Goal:** install the connector in a workspace, configure authentication and the agent allowlist, and call monday.com operations from your automations.
## Installation
1. Go to **Apps** in your workspace
2. Search for **monday.com** and install it
3. Open the **Configuration app** (the link auto-populated on install) to choose the auth mode, provide credentials (or paste a Personal API Token), connect a monday.com account, and allow the agents that may call the connector
## Configuration
| Field | Description |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **monday.com API Base URL** | Base URL of the monday.com API (default `https://api.monday.com`). |
| **Personal API Token** | A monday.com Personal API Token (v2) for the `accessToken` mode, stored as a workspace secret. Optional when an OAuth mode is used. |
| **Configuration app** | Auto-populated on install — open this link to choose the auth mode, connect a monday.com account (OAuth modes), and manage the authorized-agents allowlist. |
| **MCP Endpoint** | Auto-populated on install — URL of the MCP endpoint for this instance. |
The configuration app drives authentication and the agent allowlist. From it you pick one of:
| Auth mode | What you provide | Best for |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `oauthCentral` | Nothing — just click **Connect** | Workspaces on a platform where the maintainer set up the central monday.com client. |
| `oauth` | Your own monday.com **Application ID + Client Secret** (redirect URI shown in the config app: `/workspaces/slug:/webhooks/.oauthCallback`) | You manage your own monday.com OAuth app. |
| `accessToken` | A monday.com **Personal API Token (v2)** in the **Personal API Token** field | Builder automations and shared service accounts where one identity acts for the whole workspace. |
The agent allowlist (**Authorized agents**) gates which Agent Factory agents may call the MCP endpoint — see the *Agent builder* tab. Builder automations calling `Monday.op:` instructions resolve the same workspace credentials; the per-user OAuth modes apply to MCP tool calls made by Agent Factory agents.
## Available Instructions
Every instruction resolves credentials from the workspace configuration. All IDs are numeric strings. Most list operations accept `limit` and `page` (25 per page by default).
### Boards
| Instruction | Description | Returns |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `boards` | List boards, optionally filtered by `ids`, `workspace_ids`, `state`, `order_by`, `board_kind`. | `{ boards: [{ id, name, board_kind, state }] }` |
| `get_board` | Get one board by `id` with its groups, columns and paged items. | `{ id, name, groups, columns, items_page }` |
| `create_board` | Create a board (`board_name`, `board_kind` required; `workspace_id`, `folder_id`, owners/subscribers, `template_id`, `empty` optional). | `{ id, name }` |
| `update_board` | Update one `board_attribute` (`name`/`description`/`communication`) with `new_value`. | `{ id }` |
| `duplicate_board` | Duplicate a board by `duplicate_type` (with/without pulses, updates, structure). | `{ id, name }` |
| `archive_board` / `delete_board` | Archive or permanently delete a board by `board_id`. | `{ id, state }` |
### Items & Subitems
| Instruction | Description | Returns |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `items_page` | Cursor-paginated items of `board_ids`, optional `query_params` rules. | `{ cursor, items: [{ id, name, column_values }] }` |
| `items_page_by_column_values` | Items of `board_id` filtered by `columns` (`[{ column_id, column_values }]`). | `{ cursor, items: [...] }` |
| `get_items` | Fetch items by `ids` (max 100). | `{ items: [{ id, name, column_values }] }` |
| `create_item` | Create an item (`board_id`, `item_name` required; `group_id`, `column_values`, `create_labels_if_missing`). | `{ id, name }` |
| `create_subitem` | Create a subitem under `parent_item_id`. | `{ id, name }` |
| `duplicate_item` | Duplicate an item on `board_id`, optionally `with_updates`. | `{ id }` |
| `move_item_to_group` | Move `item_id` to `group_id` on the same board. | `{ id }` |
| `move_item_to_board` | Move `item_id` to `board_id`/`group_id`, mapping columns and subitem columns. | `{ id }` |
| `archive_item` / `delete_item` | Archive or delete `item_id`. | `{ id, state }` |
| `clear_item_updates` | Clear all updates posted on `item_id`. | `{ id }` |
### Columns
| Instruction | Description | Returns |
| ------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `columns` | List columns of `board_id` with types and JSON settings. | `{ columns: [{ id, title, type, settings_str }] }` |
| `create_column` | Create a column (`board_id`, `title`, `column_type` required; one of 37 types). | `{ id, title, type }` |
| `change_column_title` | Rename a column (`board_id`, `column_id`, `title`). | `{ id, title }` |
| `change_column_metadata` | Update a column's `title` or `description` (`column_property` + `value`). | `{ id }` |
| `delete_column` | Delete `column_id` from `board_id`. | `{ id }` |
| `change_column_value` | Update a value with a typed JSON `value` (`board_id`, `column_id` required; `item_id`). | `{ id }` |
| `change_simple_column_value` | Update a value with a simple string `value`. | `{ id }` |
| `change_multiple_column_values` | Update several columns via `column_values` map. | `{ id }` |
### Groups
| Instruction | Description | Returns |
| -------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------ |
| `groups` | List groups of `board_ids`. | `{ groups: [{ id, title, color }] }` |
| `create_group` | Create a group (`board_id`, `group_name`; optional `position`, `relative_to`). | `{ id, title }` |
| `update_group` | Update a `group_attribute` (`title`/`color`/`position`/relative) with `new_value`. | `{ id }` |
| `duplicate_group` | Duplicate `group_id` (`add_to_top`, `group_title` optional). | `{ id, title }` |
| `archive_group` / `delete_group` | Archive or delete `group_id`. | `{ id }` |
### Users & Teams
| Instruction | Description | Returns |
| ---------------------------------------------- | ----------------------------------------------------------- | ---------------------------------- |
| `users` | List users (filter by `ids`, `emails`, `name`, `kind`). | `{ users: [{ id, name, email }] }` |
| `me` | Get the user whose token is used. | `{ id, name, email, account }` |
| `invite_users` | Invite users by `emails` (optional `user_role`, `product`). | `{ invited: [...] }` |
| `deactivate_users` | Deactivate `user_ids`. | `{ deactivated: [...] }` |
| `teams` | List teams (optional `ids`). | `{ teams: [{ id, name }] }` |
| `add_users_to_team` / `remove_users_from_team` | Manage team membership (`team_id`, `user_ids`). | `{ id }` |
### Workspaces
| Instruction | Description | Returns |
| ----------------------------- | ------------------------------------------------------------ | -------------------------------------- |
| `workspaces` | List workspaces (optional `kind`, `state`). | `{ workspaces: [{ id, name, kind }] }` |
| `create_workspace` | Create a workspace (`name`, `kind` required). | `{ id, name }` |
| `update_workspace` | Update workspace `attributes` (`{name, kind, description}`). | `{ id }` |
| `delete_workspace` | Delete `workspace_id`. | `{ id }` |
| `add_users_to_workspace` | Add `user_ids` as `subscriber`/`owner` of `workspace_id`. | `{ id }` |
| `delete_users_from_workspace` | Remove `user_ids` from `workspace_id`. | `{ id }` |
### Updates (comments)
| Instruction | Description | Returns |
| ------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------- |
| `updates` | List updates globally (paginated). | `{ updates: [{ id, body, creator_id }] }` |
| `item_updates` | List updates attached to `item_id`. | `{ updates: [...] }` |
| `create_update` | Create an update on `item_id` (`body` required; optional `parent_id`). | `{ id }` |
| `edit_update` / `delete_update` | Edit or delete an update by `id`. | `{ id }` |
| `pin_to_top` / `unpin_from_top` | Pin or unpin an update by `id`. | `{ id }` |
| `like_update` / `unlike_update` | Like or unlike an update by `update_id`. | `{ id }` |
### Tags & Assets
| Instruction | Description | Returns |
| ------------------- | --------------------------------------------------------------------------------- | --------------------------------- |
| `tags` | List public tags of the account (optional `ids`). | `{ tags: [{ id, name, color }] }` |
| `board_tags` | List tags of a private/shareable `board_id`. | `{ tags: [...] }` |
| `create_or_get_tag` | Create a public tag (`tag_name`; optional `board_id`) or return the existing one. | `{ id, name }` |
| `assets` | Get file assets by `ids`. | `{ assets: [{ id, name, url }] }` |
### Webhooks & Notifications
| Instruction | Description | Returns |
| --------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `webhooks` | List webhooks registered on `board_id` (optional `app_webhooks_only`). | `{ webhooks: [{ id, event, config }] }` |
| `create_webhook` | Subscribe a webhook to `board_id` (`url`, `event`; `config` required for specific-column/group events). | `{ id, board_id }` |
| `delete_webhook` | Delete a webhook by `id`. | `{ id }` |
| `create_notification` | Send an in-app notification (`user_id`, `target_id`, `text`, `target_type`). | `{ id }` |
### Docs
| Instruction | Description | Returns |
| --------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------- |
| `docs` | List docs (filter by `ids`, `object_ids`, `workspace_ids`). | `{ docs: [{ id, name, doc_kind }] }` |
| `doc_blocks` | Fetch ordered blocks of `doc_id`. | `{ blocks: [{ id, type, content }] }` |
| `create_doc` | Create a doc via `location` (`{workspace: {...}}` or `{board: {item_id, column_id}}`). | `{ id }` |
| `create_doc_block` | Add a block to `doc_id` (`type`, `content` required). | `{ id }` |
| `update_doc_block` / `delete_doc_block` | Update or delete a block by `block_id`. | `{ id }` |
### Folders
| Instruction | Description | Returns |
| --------------- | --------------------------------------------------------------------------------- | ------------------------------------ |
| `folders` | List folders (filter by `ids`, `workspace_ids`). | `{ folders: [{ id, name, color }] }` |
| `create_folder` | Create a folder in `workspace_id` (`name`; optional `color`, `parent_folder_id`). | `{ id, name }` |
| `update_folder` | Rename or recolor `folder_id`. | `{ id }` |
| `delete_folder` | Delete `folder_id` (its contents move to the workspace root). | `{ id }` |
### Meta & Admin
| Instruction | Description | Returns |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `activity_logs` | Activity log of `board_ids`, filtered by `from`/`to`, `user_ids`, `column_ids`, `group_ids`, `item_ids`. | `{ activity_logs: [{ id, event, created_at }] }` |
| `board_views` | List views configured on `board_id`. | `{ views: [{ id, name, type }] }` |
| `account` | Account meta (name, slug, tier, members, logo). | `{ id, name, slug, tier }` |
| `account_products` | Products installed on the account (CRM, Dev, Service, WM, …). | `{ products: [...] }` |
| `complexity` | Remaining complexity budget of the API token (per-minute). | `{ complexity: { after, reset_in_x_seconds } }` |
| `version` | API version currently served. | `{ version }` |
| `graphql` | Run a raw monday.com GraphQL `query` (with optional `variables`) — the escape hatch for endpoints with no dedicated instruction. | `{ data, account_id }` |
`Returns` shows the shape of the operation output (the underlying monday.com GraphQL resource).
## DSUL Examples
### Create a Board With an Item
```yaml theme={null}
- Monday.create_board:
board_name: Q2 Roadmap
board_kind: private
workspace_id: '{{workspace_id}}'
output: board
- Monday.create_item:
board_id: '{{board.id}}'
item_name: Ship onboarding revamp
group_id: topics
column_values:
status:
label: Working on it
date:
date: 2026-05-15
create_labels_if_missing: true
output: item
```
### Update a Status Column
```yaml theme={null}
- Monday.change_simple_column_value:
board_id: '{{board_id}}'
item_id: '{{item_id}}'
column_id: status
value: Done
output: result
```
### Post an Update and Notify a User
```yaml theme={null}
- Monday.create_update:
item_id: '{{item_id}}'
body: Deployed to staging.
output: update
- Monday.create_notification:
user_id: '{{owner_id}}'
target_id: '{{item_id}}'
text: Staging is ready for review
target_type: Project
```
### Paginate Items of a Board
```yaml theme={null}
- Monday.items_page:
board_ids:
- '{{board_id}}'
limit: 100
output: firstPage
- Monday.items_page:
board_ids:
- '{{board_id}}'
cursor: '{{firstPage.cursor}}'
output: nextPage
```
### Run a Raw GraphQL Query
```yaml theme={null}
- Monday.graphql:
query: 'query ($ids: [ID!]) { boards (ids: $ids) { id name owners { id } } }'
variables:
ids:
- '{{board_id}}'
output: raw
```
***
## Error Handling
| HTTP Status | Error | Solution |
| ----------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 | Unauthorized | The monday.com token is missing, invalid or expired. Reconnect via the config app (OAuth modes), or regenerate the Personal API Token in *Developer center > My access tokens*. |
| 403 | Forbidden | Check the board/workspace permissions of the connected user or token owner. |
| 404 | Not Found | Verify board, item, group, column or doc IDs (call the parent list tool first). |
| 422 | Unprocessable | Invalid column value or argument shape — see Common Issues. |
| 429 | Rate Limited | monday.com enforces a per-minute complexity budget — call `complexity` to inspect it and back off. |
| 500 | Server error | Transient monday.com error — retry shortly. |
### Common Issues
**"This agent is not authorized to use this connector"** — The calling agent is not in the allowlist. Open the configuration app → **Authorized agents** → tick this agent (id is shown in the error) or enable **Allow all agents**, and Save. The **Install capability** button does this for you.
**"The calling agent could not be identified"** — The MCP capability *Scope* does not declare `agent_id`, so Agent Factory never injects the agent identity. Set the Scope to `context_id,agent_id,user_id` on the capability (this is separate from the monday.com OAuth scopes), then allow the agent in the config app.
**"monday.com is not connected for this user"** — No per-user OAuth token is stored for the caller. Open the configuration app (OAuth mode) and click **Connect**, or use the agent's connect flow. In the `accessToken` mode, paste a Personal API Token in the config app instead.
**"monday.com token refresh failed … must reconnect"** — The stored refresh token was rejected by monday.com (revoked / expired). The connection is dropped automatically; the user must reconnect from the config app.
**"monday.com OAuth is not configured"** — Neither a tenant OAuth client nor the central platform client is available. Set the OAuth client id/secret in the config app (tenant mode), or ask the platform maintainer to provision the central OAuth client from the core workspace's config app.
**"Complexity budget exceeded"** — monday.com rate limits by query complexity, not request count. Large `items_page` calls can exhaust the budget quickly. Paginate with smaller `limit`, or fetch fewer columns.
**"Invalid column value"** — The payload shape depends on the column type. Prefer `change_simple_column_value` for simple types (text, numbers, status) and `change_column_value` for complex ones (people, dropdown, timeline). `create_labels_if_missing` only applies to `status` and `dropdown` columns.
## External Resources
Official monday.com API reference.
Per-column-type payload reference.
Webhook events and payloads.
Learn how Agent Factory agents consume MCP tools in Prisme.ai.