MCP tools

The Comindwork MCP server exposes your workspace data as tools that AI assistants can call. This lets you query records, run aggregations, view history, and more - all through natural language.

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

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 cisco, the URL is https://mcp.comind.work/cisco.

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

Claude Code

Add to your project's .mcp.json:

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

VS Code

Configure the MCP server in your VS Code MCP extension settings. The server supports OAuth-based authentication with localhost redirect.

Usage examples

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

"Find records mentioning 'budget approval'"

The AI calls search_records with query="budget approval".

Reading attachments

"What does the screenshot in TICKET456 show?"

The AI calls get_asset to retrieve the image, then describes it.

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

"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

"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

"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

Every record has a unique slug in the format WORKSPACE/APP123 (e.g., QMS/SOP123, 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

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

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 (e.g., keeper_id can be referenced as keeper).

Special values

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

Writing records

The create_record and update_record tools accept field values in natural language. The server automatically resolves friendly names to the values the platform expects:

• 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 transitions are possible (e.g., "approve", "close", "reopen").

Response format

API responses use a compact tab-separated format (not JSON) to minimize token consumption. This makes AI interactions faster and cheaper.

• 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

• Rate limit - 20 requests per minute per user. 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

• 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
• Sensitive fields (passwords, API keys) are automatically detected and filtered before reaching the AI provider