# SuiteDash MCP tools

> Every SuiteDash MCP tool on the Cotlet server: tool names, input schemas, a tools/call example and an example result for each tool.

Source: https://cotlet.dev/docs/mcp/suitedash

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

14 tools for SuiteDash on the Cotlet MCP server. Your agent picks them from tools/list.

- MCP server: `https://cotlet.dev/mcp/v1`
- Connects with: Your own SuiteDash account (admin for invoices, payments and the CRM)
- Integration page: https://cotlet.dev/integrations/suitedash-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `suitedash_find_contact` | read | Contacts and companies by name or email, with role, company and custom fields. |
| `suitedash_list_projects` | read | Projects with client, status, Project Leader, start and estimated completion dates. |
| `suitedash_list_tasks` | read | Tasks with assignee, due date, priority, status and project. |
| `suitedash_list_invoices` | read | Invoices with number, client, title, total, amount paid, due date and status. |
| `suitedash_get_invoice` | read | Full invoice: line items, discounts, taxes, payments, notes and payment link. |
| `suitedash_list_message_threads` | read | Secure Messaging threads with subject, participants, last message and unread flag. |
| `suitedash_create_contact` | write | New Lead, Prospect or Client in your CRM. No portal invitation is sent. |
| `suitedash_create_project` | write | New project for a client, optionally from a Task Template. |
| `suitedash_add_task` | write | New task in a project or standalone, assigned to a teammate. |
| `suitedash_complete_task` | write | Mark a task as Completed. |
| `suitedash_create_invoice` | write | Invoice for a client from your Office items. Saved as Draft unless you open and send it. |
| `suitedash_record_payment` | write | Record a payment made outside SuiteDash against an open invoice. |
| `suitedash_send_message` | write | New Secure Messaging thread, or a reply in an existing one. |
| `suitedash_share_file` | write | Upload a file to the Sharing Folder of a client. |

## Find contact

MCP tool: `suitedash_find_contact`

Access: read.

Searches your CRM by name, company name or email and returns the matches with their UID, role and company. Use the UID as client_id or contact_id in the other tools. Role is Lead, Prospect or Client as in your CRM.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Name, company name or email. |
| `role` | enum | no | lead, prospect or client. Default: any. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "suitedash_find_contact",
    "arguments": {
      "query": "query"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "contacts": [
      {
        "contact_id": "c7f2a9e1-4b3d-4e8a-9f10-2d6b5a8c3e71",
        "name": "Ana Lopez",
        "email": "ana@acmestudio.example",
        "role": "client",
        "company": "Acme Studio"
      }
    ]
  },
  "isError": false
}
```

## List projects

MCP tool: `suitedash_list_projects`

Access: read.

Lists projects, optionally for one client. Archived projects are left out unless you ask. Use project_id in add_task and list_tasks.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | no | Only projects of this contact or company. |
| `include_archived` | boolean | no | Include archived projects. Default: false. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "suitedash_list_projects",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "projects": [
      {
        "project_id": "p_2201",
        "name": "Website Redesign",
        "client": "Acme Studio",
        "status": "In progress",
        "leader": "you@yourcompany.example",
        "start_date": "2026-10-12",
        "completion_date": "2026-12-01"
      }
    ]
  },
  "isError": false
}
```

## List tasks

MCP tool: `suitedash_list_tasks`

Access: read.

Lists tasks across your account, or in one project. Set mine_only to see your My Tasks list. Completed tasks are left out unless you ask.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `project_id` | string | no | Only tasks in this project. |
| `mine_only` | boolean | no | Only tasks assigned to you (My Tasks). Default: false. |
| `include_completed` | boolean | no | Include completed tasks. Default: false. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "suitedash_list_tasks",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "tasks": [
      {
        "task_id": "t_8841",
        "title": "Kickoff call",
        "project": "Website Redesign",
        "assigned_to": "you@yourcompany.example",
        "due_date": "2026-10-14",
        "priority": "Normal",
        "status": "Open"
      }
    ]
  },
  "isError": false
}
```

## List invoices

MCP tool: `suitedash_list_invoices`

Access: read.

Lists invoices from Office, newest first. Filter by status, client or due date to find what is overdue. Total and amount paid are in the invoice currency, so a partial payment shows what is still owed.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `status` | enum | no | draft, open, partially_paid or paid. Default: open. |
| `client_id` | string | no | Only invoices of this client. |
| `due_before` | date | no | Only invoices due before this date. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "suitedash_list_invoices",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "invoices": [
      {
        "invoice_id": "58213",
        "invoice_number": "1042",
        "client": "Acme Studio",
        "title": "Website design, October",
        "total": "900.00",
        "paid": "0.00",
        "currency": "USD",
        "due_date": "2026-10-10",
        "status": "open"
      }
    ]
  },
  "isError": false
}
```

## Get invoice

MCP tool: `suitedash_get_invoice`

Access: read.

Returns one invoice with its line items, payments recorded so far and the payment link your client uses. Read it before record_payment to check what is still owed.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `invoice_id` | string | yes | Invoice ID from list_invoices. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "suitedash_get_invoice",
    "arguments": {
      "invoice_id": "invoice_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "invoice_id": "58213",
    "invoice_number": "1042",
    "status": "open",
    "title": "Website design, October",
    "items": [
      {
        "item": "Design hour",
        "quantity": 10,
        "rate": "90.00",
        "amount": "900.00"
      }
    ],
    "total": "900.00",
    "paid": "0.00",
    "payments": [],
    "currency": "USD",
    "due_date": "2026-10-24",
    "payment_link": "https://yourname.suitedash.com/pay/invoice/58213"
  },
  "isError": false
}
```

## List message threads

MCP tool: `suitedash_list_message_threads`

Access: read.

Lists Secure Messaging threads in a folder, most recent first, with the last message and an unread flag. The folder is Inbox unless you name another. Use thread_id to reply with send_message.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `folder` | string | no | Folder name. Default: Inbox. |
| `unread_only` | boolean | no | Only threads with unread messages. |
| `limit` | integer | no | 1 to 50. Default: 20. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "suitedash_list_message_threads",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "threads": [
      {
        "thread_id": "th_3a91",
        "subject": "Deadline for the logo files",
        "participants": [
          "Ana Lopez"
        ],
        "last_message": "Can we move the deadline to Friday?",
        "unread": true,
        "updated_at": "2026-10-09T15:40:00Z"
      }
    ]
  },
  "isError": false
}
```

## Create contact

MCP tool: `suitedash_create_contact`

Access: write.

Adds one contact to your CRM and links it to a company, creating the company if it does not exist. No portal invitation or email goes out, and one edit in SuiteDash undoes it, so this tool runs without asking.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `first_name` | string | yes | First name. |
| `last_name` | string | yes | Last name. |
| `email` | string | yes | Email address. |
| `role` | enum | yes | lead, prospect or client. |
| `company_name` | string | no | Company to link, created if it does not exist. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "suitedash_create_contact",
    "arguments": {
      "first_name": "first name",
      "last_name": "last name",
      "email": "jane@example.com",
      "role": "lead"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "contact_id": "c7f2a9e1-4b3d-4e8a-9f10-2d6b5a8c3e71",
    "name": "Jane Doe",
    "role": "client",
    "company": "Doe Studio",
    "status": "created"
  },
  "isError": false
}
```

## Create project

MCP tool: `suitedash_create_project`

Access: write.

Creates a project for one client. With task_template, the project gets that template's tasks and phases. Nothing is sent to the client, and the project can be archived afterwards, so this tool runs without asking.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Project Name. |
| `client_id` | string | yes | Client UID from find_contact. |
| `task_template` | string | no | Task Template name; adds its tasks and phases. |
| `start_date` | date | no | Project Start Date. |
| `completion_date` | date | no | Estimated Completion Date. |
| `estimated_value` | string | no | Estimated value, e.g. "2500 USD". |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "suitedash_create_project",
    "arguments": {
      "name": "Jane Doe",
      "client_id": "client_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "project_id": "p_2201",
    "name": "Website Redesign",
    "client_id": "c7f2a9e1-4b3d-4e8a-9f10-2d6b5a8c3e71",
    "status": "created",
    "start_date": "2026-10-12",
    "completion_date": "2026-12-01"
  },
  "isError": false
}
```

## Add task

MCP tool: `suitedash_add_task`

Access: write.

Adds a task to a project, or a standalone task when project_id is empty. It is assigned to you unless you give a staff email. Priority uses the names in your account. Runs without asking: the task reaches only your team and complete_task closes it.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `title` | string | yes | Task title. |
| `project_id` | string | no | Project from list_projects. Empty: standalone task. |
| `assigned_to` | string | no | Staff email. Default: you. |
| `due_date` | date | no | Due Date. |
| `priority` | string | no | Priority as named in your account. Default: Normal. |
| `description` | string | no | Task description. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "suitedash_add_task",
    "arguments": {
      "title": "title"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "task_id": "t_8841",
    "title": "Kickoff call",
    "project_id": "p_2201",
    "assigned_to": "you@yourcompany.example",
    "due_date": "2026-10-14",
    "status": "created"
  },
  "isError": false
}
```

## Complete task

MCP tool: `suitedash_complete_task`

Access: write.

Marks one task as Completed. It runs without asking, because it reaches no client and one edit in SuiteDash reopens the task.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `task_id` | string | yes | Task ID from list_tasks. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "suitedash_complete_task",
    "arguments": {
      "task_id": "task_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "task_id": "t_8841",
    "status": "completed"
  },
  "isError": false
}
```

## Create invoice

MCP tool: `suitedash_create_invoice`

Access: write. Confirm: waits for the user's OK before it runs.

Creates an invoice for one client from items set up in Office, with a due date. The total is the sum of quantity times rate. With status draft nothing is sent. With status open the client can pay it, and notify_client sends the New Invoice notification. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | yes | Client UID from find_contact. |
| `title` | string | yes | Title visible to the client. |
| `items` | object | yes | List of { item, quantity, rate }. item is an Item from Office settings. |
| `due_date` | date | yes | Due Date. |
| `status` | enum | no | draft or open. Default: draft. |
| `notify_client` | boolean | no | Send the New Invoice notification when open. Default: true. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "suitedash_create_invoice",
    "arguments": {
      "client_id": "c7f2a9e1-4b3d-4e8a-9f10-2d6b5a8c3e71",
      "title": "Website design, October",
      "items": [
        {
          "item": "Design hour",
          "quantity": 10,
          "rate": 90
        }
      ],
      "due_date": "2026-10-24",
      "status": "open",
      "notify_client": true
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "invoice_id": "58213",
    "invoice_number": "1042",
    "status": "open",
    "total": "900.00",
    "currency": "USD",
    "due_date": "2026-10-24",
    "payment_link": "https://yourname.suitedash.com/pay/invoice/58213"
  },
  "isError": false
}
```

## Record payment

MCP tool: `suitedash_record_payment`

Access: write. Confirm: waits for the user's OK before it runs.

Records a manual payment on one invoice, with a Payment Type from your account and an optional note. A partial amount leaves the invoice partially paid. send_confirmation emails the standard payment confirmation to the client. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `invoice_id` | string | yes | Invoice ID from list_invoices. |
| `amount` | string | yes | Amount paid, e.g. "900.00". |
| `payment_type` | string | yes | Payment Type as named in your account, e.g. Bank Transfer. |
| `note` | string | no | Payment note. |
| `send_confirmation` | boolean | no | Email the payment confirmation. Default: false. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "suitedash_record_payment",
    "arguments": {
      "invoice_id": "58213",
      "amount": "900.00",
      "payment_type": "Bank Transfer",
      "note": "Wire ref INV1042, received 12 Oct",
      "send_confirmation": true
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "invoice_id": "58213",
    "payment_id": "pay_7710",
    "amount": "900.00",
    "payment_type": "Bank Transfer",
    "invoice_status": "paid",
    "confirmation_sent": true
  },
  "isError": false
}
```

## Send message

MCP tool: `suitedash_send_message`

Access: write. Confirm: waits for the user's OK before it runs.

Sends a Secure Messaging message: a reply when thread_id is set, otherwise a new thread to the contacts or staff in to, with a subject. Messages go out under your name. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `to` | string[] | no | Contact UIDs or staff emails. Required for a new thread. |
| `thread_id` | string | no | Reply in this thread from list_message_threads. |
| `subject` | string | no | Subject of a new thread. |
| `body` | string | yes | Message text. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "suitedash_send_message",
    "arguments": {
      "thread_id": "th_3a91",
      "body": "Hi Ana, the final logo files are scheduled for Friday 16 Oct. You will find them in your portal."
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "thread_id": "th_3a91",
    "message_id": "msg_5502",
    "status": "sent",
    "sent_at": "2026-10-11T09:05:00+02:00"
  },
  "isError": false
}
```

## Share file

MCP tool: `suitedash_share_file`

Access: write. Confirm: waits for the user's OK before it runs.

Uploads one file from a URL to the dedicated Sharing Folder of one client. With notify, the client is told about the new file. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | yes | Contact UID from find_contact. |
| `file_url` | string | yes | Public or signed URL of the file to upload. |
| `notify` | boolean | no | Notify the contact about the new file. Default: true. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "suitedash_share_file",
    "arguments": {
      "contact_id": "contact_8c41d2",
      "file_url": "https://example.com"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "contact_id": "c7f2a9e1-4b3d-4e8a-9f10-2d6b5a8c3e71",
    "file_name": "acme-logo-final.zip",
    "status": "shared",
    "notified": true
  },
  "isError": false
}
```