Menu

Mattering Productivity MCP tools

53 tools on the Mattering MCP gateway at https://mcp.mattering.io/mcp. Each call forwards your token to the Productivity User API, so a tool can do exactly what your key can do.

Connect any MCP client to https://mcp.mattering.io/mcp; it discovers the Mattering sign-in and asks you to approve the tools it may use. Tool names, parameters and descriptions below are read from the gateway source. See the MCP gateway concept page for connection details.

Attachments

productivity_get_attachment

Fetch a task attachment's contents, shaped by file kind.

Full description

Fetch a task attachment's contents, shaped by file kind.

Required: space_id.

Optional config keys: * include_content (bool, default true): set false for metadata only * max_bytes (int, default 2 MB; hard cap 10 MB): guards binaries * force_binary (bool, default false): return base64 even for text/PDF * page_limit (int, default 50): for PDF text extraction

Return shape depends on the attachment's kind:
  * image: the raw image is returned as a native MCP image content
    block (the LLM sees the image directly), alongside a JSON metadata
    block.
  * text (utf-8 source files, JSON, CSV, Markdown, logs, etc.) : 
    decoded text is returned in the JSON content.data field.
  * pdf: text is extracted with pypdf and returned in
    content.data; content.page_count and content.truncated
    indicate scope.
  * binary: returned as base64 in content.data. If the file is
    larger than max_bytes, a 413 with size info comes back instead;
    re-send with a higher max_bytes (capped at 10 MB) to fetch.

Parameters

NameTypeRequiredDefault
attachment_idstrrequirednone
payloaddictrequirednone

Calls

productivity_get_upload_url

Get a signed upload URL for direct file upload to a task.

Full description

Get a signed upload URL for direct file upload to a task.

Use this instead of upload_attachment for files larger than ~2 KB. The returned URL accepts a plain HTTP multipart POST, completely bypassing MCP transport (no base64 corruption).

Required: space_id, config with: * filename (string, including extension) * mime_type (string, optional)

Flow:
  1. Call this tool → receive upload_url and curl_command
  2. Run the curl command via shell, substituting the local file
     path for <LOCAL_FILE_PATH>
  3. The curl response contains the attachment metadata
     (public_id, file_url, etc.)

The URL is valid for 10 minutes and requires no additional auth.

Parameters

NameTypeRequiredDefault
task_idstrrequirednone
payloaddictrequirednone

Calls

productivity_list_attachments

List file attachments on a task (metadata only).

Full description

List file attachments on a task (metadata only).

Required: space_id. Optional config: limit (default 200, max 1000). Each attachment includes public_id, filename, mime_type, file_size, kind ("image"/"text"/ "pdf"/"binary"), file_url, and uploader info. Use productivity_get_attachment to fetch contents for one of them.

Parameters

NameTypeRequiredDefault
task_idstrrequirednone
payloaddictrequirednone

Calls

Comments

productivity_create_comment

Capability: add a comment to a task.

Full description

Capability: add a comment to a task.

Required: space_id, config with key content (the comment text). body is accepted as an alias for content.

Parameters

NameTypeRequiredDefault
task_idstrrequirednone
payloaddictrequirednone

Calls

productivity_list_comments

List comments on a task in chronological order.

Full description

List comments on a task in chronological order.

Required: space_id. Optional config: limit (default 200, max 1000), order ("asc" for oldest-first or "desc" for newest-first; default "asc").

Parameters

NameTypeRequiredDefault
task_idstrrequirednone
payloaddictrequirednone

Calls

Custom fields

productivity_manage_custom_field

Create / update / delete a workspace custom field.

Full description

Create / update / delete a workspace custom field.

Required: action, space_id. Create: name, field_type; optional options, default_value, is_required, widget_ids. Update / delete: field_id.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_manage_custom_field_preset

Create / update / delete / set-default a workspace custom-field preset.

Full description

Create / update / delete / set-default a workspace custom-field preset.

Custom-field presets are reusable named bundles of existing workspace custom fields that widgets can reference via productivity_configure_widget_view(custom_field_preset_id=...).

Required: action ('create' | 'update' | 'delete' | 'set_default'), space_id. Create: name; optional description, is_default, custom_field_ids: list of workspace custom-field public_ids in the desired display order. Update: preset_id plus any of the create fields. When custom_field_ids is provided, the list fully replaces the current preset members. Delete / set_default: preset_id.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_manage_status_preset

Create / update / delete / set-default a workspace status preset.

Full description

Create / update / delete / set-default a workspace status preset.

Status presets are reusable named lists of statuses (each with a name + color) that widgets can reference via productivity_configure_widget_view(status_preset_id=...). Editing a preset updates every widget that references it.

Required: action ('create' | 'update' | 'delete' | 'set_default'), space_id. Create: name; optional description, is_default, statuses: list of {name, color, order?} dicts. Update: preset_id plus any of the create fields. When statuses is provided, the list replaces the current items (matching by id where present, otherwise create-or-delete). Delete / set_default: preset_id.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

Diagnostics

productivity_list_capabilities

List the productivity service's registered capabilities (debug helper).

Full description

List the productivity service's registered capabilities (debug helper).

Returns the available capability names, HTTP methods, paths, categories, and required / optional parameter lists. Useful for discovering what the service exposes without paging through the docs.

Takes no parameters.

Knowledge base

productivity_manage_kb

Create / update / delete / reorder Knowledge Base categories & articles, and upload images.

Full description

Create / update / delete / reorder Knowledge Base categories & articles, and upload images.

Required: widget_id (a DOCS widget), entity ("category" | "article" | "image"), action ("create" | "update" | "delete" | "reorder"; "upload" for images).

Category payloads::

{"widget_id": "...", "entity": "category", "action": "create",
     "name": "Onboarding"}
    {"widget_id": "...", "entity": "category", "action": "update",
     "category_id": "...", "name": "New name"}
    {"widget_id": "...", "entity": "category", "action": "delete",
     "category_id": "..."}                      # articles become Uncategorized
    {"widget_id": "...", "entity": "category", "action": "reorder",
     "order": ["catId1", "catId2", ...]}

Article payloads::

{"widget_id": "...", "entity": "article", "action": "create",
     "title": "Welcome", "content": "<p>HTML…</p>",
     "category_id": "...",            # optional; omit = Uncategorized
     "status": "draft"}               # "draft" (default) | "published"
    {"widget_id": "...", "entity": "article", "action": "update",
     "article_id": "...", "title": "...", "content": "...",
     "status": "published", "category_id": "...", "order": 2}
    {"widget_id": "...", "entity": "article", "action": "delete",
     "article_id": "..."}
    {"widget_id": "...", "entity": "article", "action": "reorder",
     "order": ["artId1", "artId2", ...]}

Image payload (embed pictures in articles)::

{"widget_id": "...", "entity": "image", "action": "upload",
     "image_base64": "<base64 or data-URL, max 10 MB decoded>",
     "filename": "diagram.png",       # extension decides the type:
                                      # jpg/jpeg/png/gif/webp/svg
     "title": "Architecture diagram"} # optional alt text

The response carries the stored image's url and a ready-made embed_html (<img src="…">): include that snippet in an article's content to display the image. Never inline base64 data-URLs in content; upload here and embed the URL instead.

content is Quill rich-text HTML. status controls visibility: published articles are visible to all viewers; draft articles are editor-only. Publishing/unpublishing is just an update that sets status.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_query_kb

Read a Knowledge Base (DOCS) widget's categories and articles.

Full description

Read a Knowledge Base (DOCS) widget's categories and articles.

Type-code note: DOCS is the KNOWLEDGE BASE widget (what this tool reads); NOTES is the separate DOCUMENT widget (a single rich-text note) and has no categories/articles: don't point this tool at one.

Required: space_id, config (with widget_id: a DOCS widget). Optional config keys:

article_id : return a single article including its content
                  (Quill HTML). Draft articles are only returned to
                  editors.
    query      : case-insensitive search over article title + body;
                  returns up to 50 matches.

With neither article_id nor query, returns the full tree: categories (id, name, order) and articles (id, title, status, order, category_id). can_edit reflects the caller's edit rights; non-editors only ever see published articles.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

Notifications

productivity_send_notification

Capability: send an in-app notification.

Full description

Capability: send an in-app notification.

Required: space_id, config.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

Projects

productivity_get_project_canvas

Get a project's tabs and widgets with full configs.

Full description

Get a project's tabs and widgets with full configs.

Widget type codes vs names: DOCS is the KNOWLEDGE BASE widget and NOTES is the DOCUMENT widget: the stored codes predate the display names and never changed. Each widget carries widget_type_label with the human name, and a blank title falls back to that label; present widgets to users by label/title, never by the raw type code.

Parameters

NameTypeRequiredDefault
project_idstrrequirednone

Calls

productivity_manage_folder

Create / rename / delete a folder.

Full description

Create / rename / delete a folder.

Required: action ('create' | 'rename' | 'delete'), space_id. Rename / delete: folder_id. Create / rename: name.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_manage_project

Create / update / delete a project.

Full description

Create / update / delete a project.

Required: action ('create' | 'update' | 'delete'), space_id. Create: name, folder_id (must resolve to an existing folder in the space: projects without a folder are rejected); optional description, status, owner_username. Update / delete: project_id plus updatable fields. On update, folder_id may be passed as "" / "0" to detach the project from its current folder.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_manage_tab

Create / update / delete a project tab.

Full description

Create / update / delete a project tab.

Required: action, project_id. Create: name, optional is_default. Update / delete: tab_id.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

Queries

productivity_query_batch

Query tasks within a batch with filters.

Full description

Query tasks within a batch with filters.

Required: space_id, config. Paginated: put limit (default 50, max 200) and offset in config; the response meta carries total / has_more so you can page a large batch instead of pulling it all at once.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_query_project

Query tasks within a project with filters.

Full description

Query tasks within a project with filters.

Required: space_id, config. Paginated: put limit (default 50, max 200) and offset in config; the response meta carries total / has_more so you can page a large project instead of pulling it all at once.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_query_task

Query a single task by ID with optional includes.

Full description

Query a single task by ID with optional includes.

Required: space_id, config (with task_id).

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_query_widget

Query tasks within a widget / list with filters.

Full description

Query tasks within a widget / list with filters.

Required: space_id, config. Paginated: put limit (default 50, max 200) and offset in config; the response meta carries total / has_more. Never pull a large widget's list unfiltered in one call: page it, or add config.filters to scope it.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

Recordings

productivity_extract_recording_context

Capability: extract visual context (frames + transcript) from a recording.

Full description

Capability: extract visual context (frames + transcript) from a recording.

Required: space_id, config.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_list_recordings

List screen/video recordings on a task (metadata only).

Full description

List screen/video recordings on a task (metadata only).

Recordings are a SEPARATE model from attachments: the in-app screen recorder and the task-card video uploader create TaskRecording rows, which productivity_list_attachments does NOT return. Use this to see videos uploaded to a card.

Required: space_id. Optional config: limit (default 200, max 1000). Each recording includes public_id, filename, duration, formatted_duration, file_size, file_url (in-app download), gcs_uri (worker-fetchable storage URI), managed_file_id, transcript_status, and uploader info.

Parameters

NameTypeRequiredDefault
task_idstrrequirednone
payloaddictrequirednone

Calls

Tasks

productivity_add_tag

Capability: add a tag to a task.

Full description

Capability: add a tag to a task.

Required: space_id, config.

Parameters

NameTypeRequiredDefault
task_idstrrequirednone
payloaddictrequirednone

Calls

productivity_assign_task

Capability: assign (or unassign) a task.

Full description

Capability: assign (or unassign) a task.

Required: space_id, config with assignee_username (an email or username; assignee_email / assignee / assignee_id are accepted too) or unassign: true. Optional config.task_ids assigns several tasks at once. A config that names nobody is an error, never a silent tasks_assigned: 0.

Parameters

NameTypeRequiredDefault
task_idstrrequirednone
payloaddictrequirednone

Calls

productivity_create_subtask

Capability: create a subtask under an existing task.

Full description

Capability: create a subtask under an existing task.

Required: space_id, config (subtask fields). Optional: user_id, execution_payload.

Parameters

NameTypeRequiredDefault
task_idstrrequirednone
payloaddictrequirednone

Calls

productivity_create_task

Capability: create a task via the automation engine.

Full description

Capability: create a task via the automation engine.

Required: space_id, config. Optional: user_id, execution_payload.

ALWAYS pass config.widget_id (a TASKS widget): it binds the task to the widget's backing list (auto-created if needed) so it shows up in the UI. Passing only config.project_id creates the task at project level, unattached to any widget and invisible in every widget view; the response flags this with placement: "project" and a warning. Prefer productivity_manage_task / productivity_create_tasks_bulk for new integrations.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_create_task_with_subtasks

Create a parent task plus subtasks in one call.

Full description

Create a parent task plus subtasks in one call.

Required: widget_id, title, subtasks (list of {title, description?, status?, assignee_username?, due_date?}).

Same write-time guarantee as productivity_manage_task: the widget_id always binds the parent + subtasks to that widget's backing list (auto-created if needed); a non-tasks widget is rejected with widget_not_a_tasks_widget.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_create_tasks_bulk

Create up to 50 tasks (each with optional subtasks) in one call.

Full description

Create up to 50 tasks (each with optional subtasks) in one call.

Required: widget_id, tasks (list of task dicts).

Same write-time guarantee as productivity_manage_task: the widget_id always binds every task to that widget's backing list (auto-created if needed); a non-tasks widget is rejected with widget_not_a_tasks_widget.

Partial failure is possible: a task whose status fails validation against the widget's status preset is skipped, not created. The response reports tasks_created (actual successes only), tasks_failed, and an errors array; skipped subtasks appear as subtask_errors on their parent entry. ALWAYS check tasks_failed / errors after a bulk create: do not treat a 200 response alone as proof every task landed.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_delete_tasks_bulk

Delete up to 200 tasks in one call.

Full description

Delete up to 200 tasks in one call.

Prefer this over looping productivity_manage_task(action='delete') per task: it executes in a single round-trip and aggregates per-task errors instead of failing the batch.

Required: space_id, task_ids (list of task public_ids, max 200).

Deleting a parent task cascades to its subtasks, so if you pass both a parent and its subtasks the subtasks come back as task_not_found once the parent is gone: that is expected, not a failure. Response includes results.tasks_deleted (count), deleted_ids (the public_ids actually removed), and an errors array describing any task_not_found misses without aborting the rest of the batch.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_list_tasks

List tasks with filters.

Full description

List tasks with filters.

Provide one of space_id, project_id, or widget_id. Optional filters: status (str or list), assignee_username, due_before, due_after, keyword, include_subtasks, limit, offset.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_manage_task

Create / update / delete a task.

Full description

Create / update / delete a task.

Required: action. Create: widget_id (required: ensures the task lands in the correct project/list), title, and optional description, status, assignee_username, due_date, parent_task_id, tags, batch_name, recurrence. Update: task_id, plus any updatable fields (title, description, status, due_date). When setting status, include widget_id to resolve the status name against that widget's status preset: required when the task lives on a widget with its own preset (e.g. env-var registry widgets). Delete: task_id.

Guarantee: when widget_id is supplied the server ALWAYS binds the task to that widget's backing list: auto-creating the list and canonicalizing the widget type first if the widget was malformed/legacy: so a task can never be silently stranded at project level and invisible in the widget. If widget_id points at a non-tasks widget (NOTES, IMAGE, …) the call is rejected with error: "widget_not_a_tasks_widget" rather than creating an orphan.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_move_task

Capability: move a task to a different widget / list.

Full description

Capability: move a task to a different widget / list.

Required: space_id, config.

Parameters

NameTypeRequiredDefault
task_idstrrequirednone
payloaddictrequirednone

Calls

productivity_remove_tag

Capability: remove a tag from a task.

Full description

Capability: remove a tag from a task.

Required: space_id, config.

Parameters

NameTypeRequiredDefault
task_idstrrequirednone
payloaddictrequirednone

Calls

productivity_serialize_task

Serialize a single task by its public_id.

Full description

Serialize a single task by its public_id.

Required: space_id. Optional: include_fields (list of field names).

Parameters

NameTypeRequiredDefault
task_idstrrequirednone
payloaddictrequirednone

Calls

productivity_update_batch_field

Capability: update a custom field on a task batch.

Full description

Capability: update a custom field on a task batch.

Required: space_id, config (batch_id, field, value).

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_update_custom_field

Capability: update a custom field value on a task.

Full description

Capability: update a custom field value on a task.

Required: space_id, config. The config must identify the field by either field_id (its public_id, preferred) or field_name (fallback), plus value. Example: {"space_id": "...", "config": {"field_id": "fdmixt55", "value": true}}.

Parameters

NameTypeRequiredDefault
task_idstrrequirednone
payloaddictrequirednone

Calls

productivity_update_task

Capability: update an existing task.

Full description

Capability: update an existing task.

Required: space_id, config. Recognized config keys: title, description (paired with update_description: true), status, due_date, clear_due_date.

When setting status, include widget_id in config to resolve the status name against that widget's status preset. **Required when the task lives on a widget with its own status preset** (e.g. env-var registry widgets whose preset differs from the project default). Without this hint the server falls back to the first TASKS widget in the task's project, which may use a different preset and reject the status name.

Parameters

NameTypeRequiredDefault
task_idstrrequirednone
payloaddictrequirednone

Calls

productivity_update_tasks_bulk

Update up to 50 tasks (any combination of fields) in one call.

Full description

Update up to 50 tasks (any combination of fields) in one call.

Prefer this over looping productivity_update_task / productivity_update_custom_field / productivity_add_tag / productivity_remove_tag per task: it executes in a single round-trip and aggregates per-task errors instead of failing the batch.

Required: space_id, updates (list, max 50). Each update is an object keyed by task_id with any subset of:

* title: new title
  * description + update_description: true: replace body
  * status: new status string
  * widget_id: widget whose status preset should be used to
    validate status. **Required when the task lives on a widget
    with its own status preset** (e.g. env-var registry widgets).
    Without this hint the server falls back to the first TASKS
    widget in the task's project, which may use a different preset
    and reject the status name.
  * due_date (YYYY-MM-DD) or clear_due_date: true
  * custom_fields: {field_name: value, ...}; sets each
    workspace custom field on the task by name
  * tags_add / tags_remove: list of tag names; missing
    tags in tags_add are auto-created in the space

Response includes aggregate results counters (tasks_updated, custom_fields_updated, tags_added, tags_removed), a per-task tasks array with the fields applied, and an errors array describing any task_not_found / field_not_found issues without aborting the rest of the batch.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

Templates

productivity_deploy_template

Capability: deploy a project / task template into a workspace.

Full description

Capability: deploy a project / task template into a workspace.

Required: space_id, config. Optional: user_id.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

Widgets

productivity_attach_widget_backing_list

Ensure a TASKS-type widget has its backing list, and optionally

Full description

Ensure a TASKS-type widget has its backing list, and optionally migrate project-level tasks into that list.

Use this when a widget renders empty in the UI even though tasks for the same project exist at project-level (visible via productivity_query_project). The endpoint creates the missing list, links it to the widget, and re-binds the migrated tasks.

Payload:
  widget_id (required): public_id of the widget to repair.
  migrate_task_ids (optional): list of task public_ids to attach to the
    backing list. Each task gets task.list = backing_list and
    task.project = None (matching the post-create state for tasks
    created against a properly-configured TASKS widget). Tasks not found
    are reported in errors; tasks already bound to the same list are
    no-ops and not counted in migrated_count.
  migrate_project_orphans (optional, default False): when True, sweep ALL
    project-level orphan tasks (task.project set, task.list NULL)
    for this widget's project into the backing list: no need to enumerate
    ids. Use this for the common case where tasks were created against the
    widget before it had a backing list (they got stranded at project
    level). Only set it when this is the project's intended task widget;
    with multiple task widgets on the project it would pull every orphan
    into this one. The read-time self-heal already does this automatically
    for single-task-widget projects, so you typically only need this flag
    when a project has more than one task widget.
  normalize_widget_type (default True): if True, remap a non-canonical
    widget_type (e.g. "TASK_LIST" left over from an old bare
    .upper() of "task_list") to canonical TASKS + a
    config.view_mode, so the create-time gate passes and a backing
    list can be attached. This heals widgets that were created before
    server-side alias normalization existed.
Response:
  { success, widget_id, list_id (int), backing_list_created (bool),
    migrated_count (int), errors (list[{task_id, error}]) }

Idempotent: re-calling with the same payload after the first successful repair returns backing_list_created: False and migrated_count: 0.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_configure_widget_view

Configure view settings on a TASKS widget.

Full description

Configure view settings on a TASKS widget.

Required: widget_id, project_id. Optional: view_mode, group_by, statuses, custom_field_ids, filters, sort_column, sort_direction, status_preset_id, custom_field_preset_id.

Statuses & custom fields can be supplied two ways:
  * Inline (statuses / custom_field_ids): widget gets a
    private set, any preset reference is cleared.
  * By preset (status_preset_id / custom_field_preset_id) : 
    widget references the workspace preset; the resolved items are
    also written into config for fast reads. Pass an empty string to
    clear a reference.

Use productivity_manage_status_preset / productivity_manage_custom_field_preset to create reusable presets first, then point widgets at them.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_configure_widgets_view_bulk

Configure view settings on up to 50 TASKS widgets in one call.

Full description

Configure view settings on up to 50 TASKS widgets in one call.

Prefer this over looping productivity_configure_widget_view per-widget: it executes in a single round-trip, authorizes each project at most once, caches preset lookups across the batch, and aggregates per-update errors instead of failing the batch. Useful when applying the same status / custom-field preset to many widgets at once.

Body shape::

{
      "project_id": "<default project public_id>",  # optional default
      "updates": [
        {
          "widget_id": "<public_id>",                          # required
          "status_preset_id": "<status preset public_id>",
          "custom_field_preset_id": "<custom field preset public_id>"
        },
        {
          "widget_id": "<public_id>",
          "view_mode": "list",
          "group_by": "status",
          "sort_column": "title",
          "sort_direction": "asc"
        },
        ...
      ]
    }

Each update supports the same fields as productivity_configure_widget_view: view_mode, group_by, statuses, custom_field_ids, filters, sort_column, sort_direction, status_preset_id, custom_field_preset_id. Inline statuses / custom_field_ids clear any preset reference; empty-string preset ids clear the reference. The top-level project_id is the default for updates missing their own.

Response includes results.widgets_configured (count), a per-update widgets array (with applied_fields listing only the keys that mutated config), and an errors array describing any per-update failures (widget_not_found, status_preset_not_found, custom_field_preset_not_found, authorization failure, etc.).

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_manage_batch

List / create / update / delete a task batch on a widget.

Full description

List / create / update / delete a task batch on a widget.

Required: action ('list' | 'create' | 'update' | 'delete'), widget_id. Create: name, optional custom_fields, task_ids. Update: batch_id plus changes. Delete: batch_id.

List is PAGED: optional limit (default 100, max 500), offset, and names_only (bool: drop each batch's custom_fields, returning just id/name/task_count). The response carries total and has_more; keep paging until has_more is false. For a "which batches already exist?" dedupe check, use names_only: true: the full shape on a widget with many batches can exceed your tool-result budget and reach you truncated mid-JSON.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_manage_widget

Create / update / delete a widget on a project tab.

Full description

Create / update / delete a widget on a project tab.

Required: action, project_id. Create: tab_id, widget_type, title; optional position/size. Update / delete: widget_id.

widget_type is normalized server-side: any task-widget alias ("TASKS", "task_list", "TASK_LIST", "TASKS_LIST", "tasks_kanban", "gantt" …) collapses to canonical TASKS and a backing list is always created (the view: list/kanban/gantt/spreadsheet : is stored in config.view_mode). Non-task types (NOTES, IMAGE, IFRAME, WHITEBOARD, FILES, RECORDING, BUTTON, TIMETABLE, GOALS, TODOS) are stored uppercased as-is.

Do not confuse the two document-ish types: DOCS creates the KNOWLEDGE BASE widget (categories + articles; queried via query_kb), while NOTES creates the DOCUMENT widget (a single rich-text note). Responses include widget_type_label with the human name.

Layout grid (GridStack, 12-column)::

position_x : column (0-11)
    position_y : row (0 = top; each unit ≈ 60 px tall)
    width      : columns spanned (1-12, default 12 = full width)
    height     : rows spanned (min 2, default 4)

Recommended layouts:

Single widget      → width=12, height=6
    Two side-by-side   → left:  position_x=0, width=6, height=6
                         right: position_x=6, width=6, height=6
                         (both at same position_y)
    Three across       → width=4 each, position_x = 0 / 4 / 8

IMPORTANT: Always pass explicit position_x, position_y, width, and height on create. Omitting them silently defaults to (0, 0, 12, 4), which stacks widgets on top of each other.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

productivity_manage_widgets_bulk

Create / update / delete up to 50 widgets in one call.

Full description

Create / update / delete up to 50 widgets in one call.

Prefer this over looping productivity_manage_widget per-widget: it executes in a single round-trip, authorizes each project at most once, and aggregates per-operation errors instead of failing the batch. Useful for bootstrapping many widgets at once, restructuring tabs (delete N old widgets + create N new ones), or bulk-renaming widgets after a project rename.

Body shape (two side-by-side TASKS widgets)::

{
      "project_id": "<default project public_id>",
      "operations": [
        {"action": "create", "tab_id": "...", "widget_type": "TASKS",
         "title": "Dev",  "position_x": 0, "position_y": 0, "width": 6, "height": 6},
        {"action": "create", "tab_id": "...", "widget_type": "TASKS",
         "title": "Prod", "position_x": 6, "position_y": 0, "width": 6, "height": 6},
        {"action": "update", "widget_id": "...", "title": "..."},
        {"action": "delete", "widget_id": "..."}
      ]
    }

Each operation supports the same fields as productivity_manage_widget (including position_x, position_y, width, height: see its docstring for the grid reference and recommended layouts). The top-level project_id is used as the default for any operation that doesn't include its own project_id. widget_type is normalized server-side: any task-widget alias (TASKS, task_list, TASK_LIST, TASKS_LIST, tasks_kanban, gantt …) collapses to canonical TASKS with the view stored in config.view_mode, and TASKS-type widgets always get a backing list created with the unique-suffix naming policy.

Response includes results (created/updated/deleted counters), a per-op widgets array (with op_index, ok, and ids), and an errors array describing any per-op failures (invalid action, widget_not_found, tab_not_found, project_not_found, authorization failure, etc.) without aborting the rest of the batch.

Parameters

NameTypeRequiredDefault
payloaddictrequirednone

Calls

Workspaces

productivity_get_space_overview

Get a workspace's structure: folders, projects, and aggregate stats.

Parameters

NameTypeRequiredDefault
space_idstrrequirednone

Calls

productivity_get_workspace_data

Return full workspace metadata: projects, tabs, widgets, custom fields, members, batches.

Parameters

NameTypeRequiredDefault
space_idstrrequirednone

Calls

productivity_list_my_spaces

List spaces accessible to the current user (rich: counts, role, project names).

Full description

List spaces accessible to the current user (rich: counts, role, project names).

When the result is empty, the response is annotated with the identity this session resolved to, so an empty list can be told apart from an identity mismatch.

Takes no parameters.

Calls

productivity_list_space_projects

List projects in a workspace with optional filters.

Parameters

NameTypeRequiredDefault
space_idstrrequirednone
folder_idOptional[str]optionalnone
statusOptional[str]optionalnone
owner_usernameOptional[str]optionalnone

Calls

productivity_list_user_spaces

List spaces accessible to the current user (lightweight: public_id + name).

Full description

List spaces accessible to the current user (lightweight: public_id + name).

Empty results are annotated with the resolved identity (see productivity_list_my_spaces).

Takes no parameters.

Calls

Identity tools (every app)

The gateway registers these once, outside any app family. Call whoami first when a result looks empty.

auth_statusReport token health, expiry, bound principal, and catalog version.
get_accountReturn the current user's account profile (email, name, id).
get_organizationReturn the organization this session is currently acting as.
list_organizationsList every organization the authenticated identity belongs to.
reauthenticateExplain how to refresh this connection's authentication.
switch_accountExplain how to re-authenticate as a different account / org.
whoamiShow who this MCP session is authenticated as.
Start Free Explore our Products