# MCP tools

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.

## 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, and form layout                  |
| `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                            |

## Setup[​](#setup "Direct link to Setup")

### Claude Desktop[​](#claude-desktop "Direct link to Claude Desktop")

Add the MCP server to your Claude Desktop configuration:

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`.

```
{
  "mcpServers": {
    "comind": {
      "url": "https://mcp.comind.work/your-company"
    }
  }
}
```

### Claude Code[​](#claude-code "Direct link to Claude Code")

Add to your project's `.mcp.json`:

```
{
  "comind-mcp": {
    "type": "url",
    "url": "https://mcp.comind.work/your-company"
  }
}
```

### VS Code[​](#vs-code "Direct link to VS Code")

VS Code supports MCP servers natively. Add the server configuration to your VS Code settings. The server supports OAuth-based authentication with localhost redirect.

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

### 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. Supports time-based grouping by month or week.

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

The `list_records` and `aggregate_records` tools accept filter expressions:

```
state="open"
creation_date>"2026-01-01"
assignee="John Smith" AND priority>3
(state="open" OR state="in_progress")
```

Person and link fields accept full names and record slugs. Call `get_app_schema` first to see available field names and lookup values.

### Field aliases[​](#field-aliases "Direct link to Field aliases")

Common aliases work in filters without needing the schema:

* `workspace` for `project_alias`
* `app` for `publishing_alias`
* `keeper` for `keeper_id`
* `created_by` for `created_by_account_id`

Person fields auto-generate aliases by stripping the `_id` or `_account_id` suffix.

### Special values[​](#special-values "Direct link to Special values")

* `{current-user}` - replaced with your user ID: `keeper={current-user}`

## 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** - pass plain text or markdown and the server converts it to the required HTML format

After a write operation, the server returns a confirmation summary and a full URL to the created or updated record.

tip

Call `get_record` before updating - it shows available actions so you know what actions are possible (e.g., "approve", "close", "reopen").

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