Build Query

Build Query

Build, live-test, and debug monday.com GraphQL queries and mutations. Introspects the actual schema to ensure correctness, formats column values properly, and validates every query by executing it.

Scope

• Helps external developers write correct GraphQL for the monday.com public API
• Complements the monday MCP tools — uses them for schema introspection and live testing
• Does NOT cover SDK setup (use /monday-api:setup) or production operations (use /monday-api:ops)

Prerequisites

• The monday MCP server must be connected (check /mcp)
• A valid API token must be configured in the MCP server

Workflow

Step 1: Understand the Request

If the user hasn't specified a board ID, ask for one — most queries require it.

Flow 1: Build a Read Query

Step 1: Introspect the schema

Use mcp__monday__get_graphql_schema with operationType: "read" to find available query fields. The output lists root-level queries (e.g., boards, items, users, me) and their argument types — use this to find the right query entry point.

Then use mcp__monday__get_type_details with the return type name (e.g., Board, Item) to discover available fields. The output lists field names and their types — only request fields the developer actually needs, as every field adds to complexity cost.

Step 2: Build the query

Construct the GraphQL query with proper arguments and field selection.

Rules:

• For board items, ALWAYS use items_page (not the deprecated items field on boards)
• Use ids parameter as an array: boards(ids: [BOARD_ID])
• Keep field selection minimal — only what's needed
• Use variables for dynamic values (not string interpolation)

Step 3: Live-test the query

Execute via mcp__monday__all_monday_api with the constructed query.

Show the actual response to the developer so they can see the exact shape.

Step 4: Present working code

Show the tested query wrapped in SDK code. Define the query in a .graphql.ts file and use code-generated types:

// src/queries.graphql.ts
export const GET_BOARD_ITEMS = `
  query GetBoardItems($boardId: [ID!]!) {
    boards(ids: $boardId) {
      name
      items_page(limit: 25) {
        cursor
        items {
          id
          name
          column_values { id text value }
        }
      }
    }
  }
`;

// src/index.ts
import 'dotenv/config';
import { ApiClient } from '@mondaydotcomorg/api';
import { GET_BOARD_ITEMS } from './queries.graphql';
import type { GetBoardItemsQuery } from './generated/graphql'; // from npm run codegen

const client = new ApiClient({ token: process.env.MONDAY_API_TOKEN! });

const result = await client.request<GetBoardItemsQuery>(GET_BOARD_ITEMS, { boardId: [BOARD_ID] });

Flow 2: Build a Write Mutation

Step 1: Introspect mutation arguments

Use mcp__monday__get_graphql_schema with operationType: "write" to find the mutation.

Use mcp__monday__get_type_details to inspect required and optional arguments.

Step 2: If column values are involved, get the exact JSON format

Use mcp__monday__get_column_type_info for each column type being written. See Flow 3 for details.

The column_values argument takes a JSON string — this is the #1 source of developer errors. The JSON must be stringified and passed as a string value.

Step 3: Build the mutation with variables

Always use GraphQL variables for dynamic values:

mutation ($boardId: ID!, $groupId: String!, $itemName: String!, $columnValues: JSON) {
  create_item(
    board_id: $boardId
    group_id: $groupId
    item_name: $itemName
    column_values: $columnValues
  ) {
    id
    name
  }
}

Step 4: Confirm and test with test data

Show the complete mutation and variables to the developer. State clearly: "This mutation will write data. Shall I run it now to verify it works?"

If they confirm, execute via mcp__monday__all_monday_api. If the mutation creates an item or makes a change, that's expected — the goal is to verify the query structure is correct. Note any test items created so the developer can clean them up.

Step 5: Present working code

Show the tested mutation wrapped in SDK code with proper variable handling.

Flow 3: Column Value Formatting

This is where most developers get stuck. Each column type has a specific JSON format for writes.

Step 1: Identify column types needed

Ask which columns the developer wants to set, or inspect the board:

Use mcp__monday__get_board_info with the board ID to see column definitions.

The column IDs returned (e.g., status, date4, numbers0) are the keys to use in column_values. They are NOT the display names shown in the UI.

Example response:

{
  "columns": [
    { "id": "status", "title": "Status", "type": "status" },
    { "id": "date4", "title": "Due Date", "type": "date" },
    { "id": "numbers0", "title": "Budget", "type": "numbers" }
  ]
}

Step 2: Get the exact JSON format

Use mcp__monday__get_column_type_info for each column type. This returns the exact schema.

Step 3: Show the format with examples

Common column value formats (quick reference):

For all 40+ column types, read docs/column-types-reference.md in this plugin directory.

Step 4: Build the column_values JSON

The column_values argument is a JSON string containing an object keyed by column ID:

"{\"status_column_id\": {\"label\": \"Done\"}, \"date_column_id\": {\"date\": \"2026-01-15\"}}"

When using GraphQL variables, pass it as:

const variables = {
  columnValues: JSON.stringify({
    status: { label: "Done" },
    date4: { date: "2026-01-15" }
  })
};

Step 5: Build and test the mutation

Use change_multiple_column_values for setting multiple columns at once (preferred over calling change_simple_column_value per column).

Follow the dry-run + confirm flow from Flow 2, Steps 4-5.

Flow 4: Pagination

Pagination uses a two-phase cursor-based pattern. This is the most common source of bugs.

Phase 1: Initial query with items_page

items_page is nested inside boards or groups:

query {
  boards(ids: [BOARD_ID]) {
    items_page(limit: 100, query_params: {
      rules: [{column_id: "status", compare_value: ["Done"]}]
    }) {
      cursor
      items {
        id
        name
        column_values { id text value }
      }
    }
  }
}

• limit: max 500 items per page (default 25)
• query_params: optional filtering (cannot combine with cursor)
• Save the returned cursor value
• If cursor is null after Phase 1, all items fit in one page — no Phase 2 needed

Phase 2: Subsequent pages with next_items_page

CRITICAL: next_items_page MUST be a root-level query. Do NOT nest it inside boards {}. This is the single most common pagination bug.

query {
  next_items_page(limit: 100, cursor: "YOUR_CURSOR_HERE") {
    cursor
    items {
      id
      name
      column_values { id text value }
    }
  }
}

• When cursor returns null, you have all items
• Keep the same field selection as Phase 1

Full pagination loop in SDK code:

Define queries in a .graphql.ts file and use code-generated types:

// src/queries.graphql.ts
export const GET_BOARD_ITEMS_PAGE = `
  query GetBoardItemsPage($boardId: [ID!]!) {
    boards(ids: $boardId) {
      items_page(limit: 100) {
        cursor
        items { id name }
      }
    }
  }
`;

export const GET_NEXT_ITEMS_PAGE = `
  query GetNextItemsPage($cursor: String!) {
    next_items_page(limit: 100, cursor: $cursor) {
      cursor
      items { id name }
    }
  }
`;

// src/index.ts
import 'dotenv/config';
import { ApiClient } from '@mondaydotcomorg/api';
import { GET_BOARD_ITEMS_PAGE, GET_NEXT_ITEMS_PAGE } from './queries.graphql';
import type { GetBoardItemsPageQuery, GetNextItemsPageQuery } from './generated/graphql';

const client = new ApiClient({ token: process.env.MONDAY_API_TOKEN! });

let allItems: GetBoardItemsPageQuery['boards'][0]['items_page']['items'] = [];

// Phase 1: Initial query
const firstPage = await client.request<GetBoardItemsPageQuery>(GET_BOARD_ITEMS_PAGE, { boardId: [BOARD_ID] });
allItems.push(...firstPage.boards[0].items_page.items);
let cursor = firstPage.boards[0].items_page.cursor;

// Phase 2: Subsequent pages (root-level!)
while (cursor) {
  const nextPage = await client.request<GetNextItemsPageQuery>(GET_NEXT_ITEMS_PAGE, { cursor });
  allItems.push(...nextPage.next_items_page.items);
  cursor = nextPage.next_items_page.cursor;
}

Step: Live-test both phases

Execute the Phase 1 query via mcp__monday__all_monday_api. If items exist and a cursor is returned, execute Phase 2 to verify the full loop works.

For the full pagination reference with filtering and edge cases, read docs/pagination-patterns.md in this plugin directory.

Flow 5: Debug a Query

Step 1: Get the failing query and error

Ask the developer to paste:

• Their GraphQL query/mutation
• The error message or unexpected response

Step 2: Run diagnostics

Check these common issues in order:

Step 3: Fix and re-test

Apply the fix and execute the corrected query via mcp__monday__all_monday_api.

Step 4: Present the corrected query

Show the before/after diff and explain what was wrong.

Error Handling