# MCP tools reference The Comind.work MCP server exposes your workspace data as tools that AI assistants can call. Query records, run aggregations, view history, and more through natural language. This page is the tool-level reference. To set up a specific client, see: * [Connect Claude](/ai/connect-claude.md) - Desktop, Code (CLI), and claude.ai web * [Connect ChatGPT](/ai/connect-chatgpt.md) - custom connector via developer mode * [Connect Cursor](/ai/connect-cursor.md) or [Connect VS Code](/ai/connect-vscode.md) ## Available tools[​](#available-tools "Direct link to Available tools") | Tool | Description | | ------------------- | -------------------------------------------------------------------------------------------- | | `list_workspaces` | Discover available workspaces | | `get_workspace` | View a workspace's apps, members, and record counts | | `get_app_schema` | Understand an app's fields, lookups, actions, form layout, and saved lists | | `list_records` | Browse and filter records by workspace, app, and field values | | `search_records` | Keyword search across records | | `aggregate_records` | Totals, counts, and breakdowns (e.g., tasks by state, hours by user) | | `get_record` | Full details on a specific record - fields, attachments, and available actions | | `list_history` | View change history - who did what, when, with field diffs | | `aggregate_history` | Change-count breakdowns (e.g., changes per user per month) | | `create_record` | Create a new record in a workspace app | | `update_record` | Update an existing record's fields or fire an action | | `upload_prepare` | Prepare a one-shot URL for uploading a binary file (PDF, image, video) to attach to a record | | `get_asset` | View images or download files attached to records | | `whoami` | Identify the current user and their recent activity | ## Server URL[​](#server-url "Direct link to Server URL") The MCP server URL follows the pattern: ``` https://mcp.comind.work/ ``` For example, if your company alias is `acme`, the URL is `https://mcp.comind.work/acme`. Your administrator can confirm the alias. ## Usage examples[​](#usage-examples "Direct link to Usage examples") ### Querying records[​](#querying-records "Direct link to Querying records") > "Show me all open tickets in the SUPPORT workspace" The AI calls `list_records` with workspace="SUPPORT", app="TICKET", filter='state="open"'. ### Searching[​](#searching "Direct link to Searching") > "Find records mentioning 'budget approval'" The AI calls `search_records` with query="budget approval". ### Reading attachments[​](#reading-attachments "Direct link to Reading attachments") > "What does the screenshot in TICKET456 show?" The AI calls `get_asset` to retrieve the image, then describes it. Beyond images, `get_asset` can pull text and PDF attachments by slug (e.g. `BT/ATTACHMENT31`) so the AI can read them and answer questions about the contents. ### Creating records[​](#creating-records "Direct link to Creating records") > "Create a new task in the IT workspace titled 'Upgrade server firmware'" The AI calls `create_record` with workspace="IT", app="TASK", and the field values. ### Updating records[​](#updating-records "Direct link to Updating records") > "Change the priority of IT/TASK456 to high and assign it to John" The AI calls `update_record` with the record slug and updated field values. ### Aggregating data[​](#aggregating-data "Direct link to Aggregating data") > "How many tasks were completed this month, broken down by assignee?" The AI calls `aggregate_records` with dimensions and optional stats fields. Time-based grouping (by day, month, or year) is supported on date fields. ### Viewing history[​](#viewing-history "Direct link to Viewing history") > "Who changed TICKET789 last week?" The AI calls `list_history` with filters on workspace and time range. History queries only support metadata fields (timestamp, user, action type) - not app-specific fields, because history entries store only changed fields. ## Record slugs[​](#record-slugs "Direct link to Record slugs") Every record has a unique slug in the format `WORKSPACE/APP123` (e.g., `PROJ/DOC123`, `IT/TICKET456`). Use slugs to reference specific records in your queries. When the AI returns record references, it displays slugs as-is. Full URLs are only constructed when you specifically ask for a clickable link. ## Filters[​](#filters "Direct link to Filters") Natural-language requests translate to filter queries behind the scenes. You can combine conditions freely - "open tickets assigned to me from last month", "high-priority records still in progress", "deals over $10K closing this quarter" - and reference people by name or records by slug. The AI resolves field names and values against the app's schema. ### Saved lists[​](#saved-lists "Direct link to Saved lists") Every workspace has saved lists (curated views) such as `THISWEEK`, `MY`, or app-specific presets. Ask the AI to "use the THISWEEK list in PROJECTS" or "what's in MY?" and it queries the saved list directly instead of rebuilding the filter from scratch. If you are not sure what lists exist, ask the AI to list them for the app you care about. ## Writing records[​](#writing-records "Direct link to Writing records") The `create_record` and `update_record` tools accept field values in natural language. The server resolves friendly names to internal values: * **Field names** - use the caption shown in the UI (e.g., "Assignee") instead of the database field name * **Person fields** - pass full names ("John Smith") and the server resolves them to user IDs * **Link fields** - pass record slugs ("IT/TASK123") and the server resolves them to internal record IDs. For fields that accept multiple links, pass comma-separated slugs * **Lookup fields** - pass the display label (e.g., "High") instead of the stored value * **Richtext fields** - HTML and markdown are both accepted. Use one or the other, not both at once. If you need a table, SVG, or other structure that markdown can't express, HTML is the right choice. Inline `` is supported for embedding small diagrams, badges, or charts directly - scripts and event handlers are stripped After a write operation, the server returns a confirmation summary and a full URL to the created or updated record. tip When you ask the AI to perform a workflow action ("approve", "close", "reopen"), it looks up the record's current state and picks the right action label automatically - you do not need to know the exact label. Embedded grids replace wholesale When asking the AI to modify line items (e.g. on a Quote, an Order, or any record with embedded sub-rows), be explicit about whether you want to **add to** or **replace** the existing rows. If the AI replaces them, rows you did not mention will be deleted. Phrases like "add this line to the existing items" make the intent clear. ### Working on multiple records at once[​](#working-on-multiple-records-at-once "Direct link to Working on multiple records at once") When you ask the AI to apply the same change to many records ("close all of these", "reassign these five to Maya"), it batches them into a single call - up to 50 records at a time - rather than one call per record. `update_record` batches can mix workspaces and apps freely. Batches are not transactional: each record succeeds or fails independently, and the AI reports per-record outcomes. If you are building your own integration that hits the same endpoints directly, see [chunking large batches](/api-integrations/rest-api/saving-data.md#chunking-large-batches) for chunk-size guidance. ### Attaching files[​](#attaching-files "Direct link to Attaching files") Ask the AI to "put all pending tickets into a CSV with status, assignee, and due date, and attach it to this task" - it queries the data, builds the file, and attaches it in one update call. Two modes are available: * **Inline text** (csv, htm, html, json, markdown, md, svg, txt, xml) - up to 256 KB per file, 5 files per record. The AI authors the content directly. * **Binary upload** (PDF, image, video, zip - up to 50 MB) - available to agents that can run shell commands on your behalf (such as Claude Code), via the `upload_prepare` flow. For agents without local file access, upload binaries through the UI. The underlying upload protocol is documented in [upload and save files](/api-integrations/rest-api/upload-and-save-files.md). ## Response format[​](#response-format "Direct link to Response format") API responses use a compact tab-separated format (not JSON) to minimize token consumption. * **Richtext fields** are automatically converted from HTML to readable markdown * **Search results** include keyword highlights so the AI can locate relevant fragments * **Person and link fields** are labeled with their type so the AI can interpret references correctly ## Limits[​](#limits "Direct link to Limits") * **Rate limit** - write operations are rate-limited per user. Read operations have no rate limit. Batch your queries where possible (e.g., use `aggregate_records` instead of looping `get_record` over many items) * **Response size** - individual tool responses are capped at 100,000 characters. Use filters and pagination to narrow large result sets * **Request timeout** - requests that take longer than 30 seconds are terminated ## Access control[​](#access-control "Direct link to Access control") * MCP queries respect your user permissions - you only see data you are authorized to access * Workspace-level and app-level restrictions can be configured before giving clients access - administrators control which workspaces and apps are exposed through MCP * Identity apps (users, groups, organizations, workspaces) are read-only via MCP - the AI cannot create or modify them even if asked