# 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                           |
| `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/<your-company>
```

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** - the server expects HTML on writes. Most AI assistants handle this; if you ask the AI to format a description in markdown and the result looks broken, ask it to retry with HTML

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.

### 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. Limits:

* Up to 5 files per call
* Up to 256 KB per file
* Text formats only: csv, htm, html, json, markdown, md, svg, txt, xml

For larger files or binary formats (images, PDFs, Office documents), upload them through the UI instead.

## 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