API and MCP
MCP server
Connect Claude, ChatGPT, Cursor and other MCP clients to UserTasks: setup, authentication and the full tool list.
UserTasks runs a Model Context Protocol server at /api/mcp (streamable HTTP). AI assistants can list and start workflows, act on tasks, build workflows, decision tables and reports, read the event stream and administer the workspace — always within the credential's permissions.
Connect a client
Use an API key (Settings → API Keys) as a bearer token:
Claude Desktop / Cursor (mcpServers)
{
"mcpServers": {
"usertasks": {
"url": "https://tasks.example.com/api/mcp",
"headers": { "Authorization": "Bearer <your-api-key>" }
}
}
}Clients that support MCP OAuth discover the authorization server from /.well-known/oauth-protected-resource, register themselves and send the user through consent; no key needed. Clients that can't send headers can use ?key= when the server sets ALLOW_QUERY_KEY_AUTH=true. Browser-based clients must be listed in MCP_ALLOWED_ORIGINS.
Settings → MCP shows your server URL, ready-made client configuration and the tool groups available to you.
Permissions
Each tool requires the permission listed below. With an OAuth token, the token's scopes must also grant it. Mutating tools are audited. A key limited to certain workflows or tables (workflow_ids, table_ids) only sees those.
Good prompts
- "List my overdue tasks and complete the invoice approvals under 1 000 as Approved."
- "Build a workflow that triggers when a Vendors row is created, calls the ERP 'Get vendor' reference and assigns a review task to Accounts payable." (The
workflows_catalogtool gives the assistant every node type and authoring recipes.) - "Show failed runs in the last hour and the integration calls that caused them." (
events_listwith a trace id.)
Tool reference
Generated from the MCP tool registry:
The server currently registers 197 tools in 19 groups. A tool call is refused unless the credential holds the listed permission (and, for OAuth tokens, a scope that grants it).
Tasks
| Tool | What it does | Permission |
|---|---|---|
tasks_list | List tasks with optional filters and pagination. | tasks.view_own |
tasks_get | Get a single task by ID with full details. | tasks.view_own |
tasks_create | Create a new task. | tasks.create |
tasks_update | Update task fields. | tasks.manage_queue |
tasks_complete | Complete a task with an outcome. | tasks.complete |
tasks_escalate | Escalate a task to another user. | tasks.escalate |
tasks_redirect | Redirect a task to another user. | tasks.redirect |
tasks_respond | Accept, hold, or reject a task in the queue. | tasks.complete |
tasks_complete_workflow | Complete a workflow-assigned user_task with an outcome and resume the paused workflow. | tasks.complete |
tasks_priority_summary | Summarize task priority and due-date pressure for the current tenant. | tasks.view_own |
Workflows
| Tool | What it does | Permission |
|---|---|---|
workflows_catalog | List workflow trigger types, node types, and MCP guidance for prompt-building workflows end to end. | workflows.view |
workflows_preflight | Validate a proposed workflow graph before creation or update. | workflows.view |
workflows_resolve_dependencies | Rewrite a proposed workflow payload using explicit dependency resolutions. | workflows.view |
workflows_list | List workflow definitions. | workflows.view |
workflows_get | Get full workflow details including nodes, edges, trigger config, and optionally recent runs. | workflows.view |
workflows_create | Create a workflow with trigger, nodes, edges, and user variables. | workflows.create |
workflows_update | Save draft changes to a workflow: trigger type/config, nodes, edges, user variables, metadata, and active status. | workflows.edit |
workflows_get_definition | Get the draft definition of a workflow in author-payload shape (name, description, trigger_type, trigger_config, nodes, edges, user_variables, swimlanes, sections, tags) — the same document as GET /api/v1/workflows/{id}… | workflows.view |
workflows_publish | Publish the current draft of a workflow as a new version snapshot. | workflows.activate |
workflows_delete | Delete a workflow by ID. | workflows.delete |
workflows_toggle | Activate or deactivate a workflow. | workflows.activate |
workflows_versions_list | List version history for a workflow. | workflows.view |
workflows_version_get | Get one published version of a workflow with its full definition (nodes, edges, trigger config, variables). | workflows.view |
workflows_start | Start a workflow execution. | workflows.activate |
workflows_inputs_get | Get the input parameters a workflow run accepts (same as GET /workflows/{id}/inputs): key, label, type (text, number, boolean, date, datetime, json, select, email, url), required, default, description and options, from … | workflows.view |
workflows_runs_list | List workflow runs with status and timing information. | workflows.view_runs |
workflows_run_get | Get details of a workflow run including execution state and optionally step-by-step logs. | workflows.view_runs |
workflows_run_action | Perform an action on a workflow run: pause, resume, or cancel (same rules as POST /workflows/runs/{id}/action). | workflows.activate |
workflows_instances_list | List live instances of a workflow (runs waiting on a task/event or paused) with their current node, version, waiting-since time and open task (assignee). | workflows.view_runs |
workflows_instances_migrate | Migrate live instances to another version of the workflow (same as POST /workflows/{id}/instances/migrate). | workflows.manage_runs |
AI agents
| Tool | What it does | Permission |
|---|---|---|
agents_list | List AI agents. | agents.view |
agents_get | Get agent details by ID, including integration linkage, declared output variables, and optionally recent runs. | agents.view |
agents_create | Create a new AI agent that can be referenced in workflow run_agent nodes. | agents.create |
agents_update | Update an existing AI agent by ID, including prompt, tools, output config, governed document/file access, governed data/table scope, governed workflow scope, governed task scope, model settings, and active state. | agents.edit |
agents_delete | Delete an AI agent by ID. | agents.delete |
agents_execute | Execute an agent with a message by queueing a run. | agents.test |
agents_runs_list | List agent execution runs so MCP can audit outputs, durations, and recent agent activity. | agents.view |
Data tables
| Tool | What it does | Permission |
|---|---|---|
data_tables_list | List custom data tables. | data.view |
data_tables_get | Get a custom table schema including columns, lookup metadata, and table settings so MCP can safely build workflows, reports, and row operations against it. | data.view |
data_tables_create | Create a new custom data table. | data.create |
data_tables_update_schema | Replace the schema for an existing custom data table. | data.edit_schema |
data_tables_delete | Delete a custom data table. | data.delete |
data_rows_query | Query rows from a custom table. | data.view |
data_rows_search | Search across table rows and return matched columns/snippets to help MCP consumers show the relevant field content. | data.view |
data_rows_get | Get one row of a custom table by ID. | data.view |
data_rows_upsert | Insert or update a row in a custom table. | data.manage_rows |
data_rows_delete | Delete a row from a custom table. | data.manage_rows |
data_rows_bulk_delete | Delete several rows of a custom table at once. | data.manage_rows |
Reports
| Tool | What it does | Permission |
|---|---|---|
reports_query | Query report data from any source with filters, grouping, and aggregation. | reports.view |
reports_sources_list | List available report data sources with the columns MCP can query. | reports.view |
reports_source_get | Get a single report source with full column metadata, plus report-building helpers such as supported visualizations, chart palettes, and drill target templates. | reports.view |
reports_preview | Validate and preview a full custom report configuration before saving it. | reports.view |
reports_remediate_config | Inspect and automatically repair a custom report config before preview or save. | reports.edit_own |
reports_list | List saved custom reports that MCP can inspect or clone. | reports.view |
reports_get | Get a saved report with full configuration. | reports.view |
reports_create | Create a saved custom report. | reports.create |
reports_update | Update a saved custom report. | reports.edit_own |
reports_export | Export a saved report as portable JSON so MCP can clone or recreate the report in another tenant. | reports.view |
reports_import | Import a saved report from portable JSON. | reports.create |
reports_delete | Delete a saved report by ID. | reports.delete |
Integrations
| Tool | What it does | Permission |
|---|---|---|
connectors_list | List available built-in connector templates that MCP can use to create integrations and auto-generate references. | integrations.view |
connectors_list_installed | List the connectors configured in this workspace (tenant connectors: key, display name, enabled flag, masked config, generated integration). | integrations.view |
connectors_get | Get a connector-backed integration with its saved config, generated integration, and generated references. | integrations.view |
integrations_list | List integrations and connector-backed integrations available in the tenant. | integrations.view |
integrations_get | Get integration details (config with credentials masked as "__SECRET__") with references so MCP can inspect the callable surface before wiring workflows, agents, or reports. | integrations.view |
references_list | List integration references across the tenant. | integrations.view |
references_get | Get a single integration reference with its request config, inputs, outputs, and parent integration details. | integrations.view |
integrations_create | Create a new integration. | integrations.create |
integrations_create_bundle | Create an integration and its references in one MCP call. | integrations.create |
connectors_create | Create a connector-backed integration from a built-in connector template. | integrations.create |
connectors_update | Update a connector-backed integration. | integrations.edit |
connectors_test | Test a connector-backed integration using the connector-specific probe flow. | integrations.test |
connectors_delete | Delete a connector-backed integration including its generated references, backing integration record, and connector record. | integrations.delete |
integrations_import_api_spec | Create an API integration and references from an OpenAPI 2.0/3.x or Postman collection document. | integrations.create |
integrations_update | Update an existing integration, including its configuration and active state. | integrations.edit |
integrations_delete | Delete an integration by ID. | integrations.delete |
integrations_test | Test an integration connection and return the current connectivity result. | integrations.test |
references_create | Create an API reference for an integration. | integrations.manage_references |
references_update | Update an API reference, including request config, inputs, outputs, and metadata. | integrations.manage_references |
references_delete | Delete an API reference by ID. | integrations.manage_references |
references_bulk_delete | Delete several API references at once (all must belong to this workspace). | integrations.manage_references |
objects_list | List composite objects. | integrations.view |
objects_get | Get a composite object with all of its join sources and any auto-generated references tied to it. | integrations.view |
objects_create | Create a composite object that joins multiple data tables and/or existing references. | integrations.edit |
objects_update | Update a composite object: name, description, and/or a full replacement source list (same shape as objects_create, or the sources array returned by objects_get). | integrations.edit |
objects_delete | Delete a composite object, its join sources, and any auto-generated references tied to the object. | integrations.delete |
integrations_execute_reference | Execute an integration API reference | integrations.test |
Governance
| Tool | What it does | Permission |
|---|---|---|
users_list | List users in the tenant so MCP can discover assignees, role targets, team members, and user-context API key subjects. | team.view_members |
roles_list | List all roles (system and custom) with their permissions so MCP can target governance, assignments, and role-based automation safely. | team.view_members |
team_members_list | List users with their role assignments so MCP can understand team-wide governance context and assign work accurately. | team.view_members |
roles_manage | Create, update, or delete roles, and assign or remove roles from users. | team.change_roles |
roles_get | Get one role with its permission keys. | team.view_members |
audit_log_query | Query the permission audit log so MCP can inspect governance changes such as role creation, role assignment, and related access-control events. | team.change_roles |
teams_list | List teams with member counts so MCP can discover assignment targets, routing groups, and team organization. | team.view_members |
teams_get | Get one team with its members. | team.view_members |
teams_create | Create a new team that can be used for task routing, governance, and workflow assignment. | team.invite |
teams_update | Update a team including its name or description. | team.invite |
teams_delete | Delete a team and remove all member associations. | team.remove |
teams_add_member | Add a user to a team so the team can be used for routing, governance, and workflow assignment. | team.invite |
teams_remove_member | Remove a user from a team. | team.remove |
invitations_list | List pending invitations that have not yet been accepted. | team.invite |
invitations_send | Invite someone to the tenant by email. | team.invite |
invitations_revoke | Revoke (delete) a pending invitation | team.invite |
invitations_resend | Email a pending invitation again with a fresh link and a new 7-day expiry. | team.invite |
API keys
| Tool | What it does | Permission |
|---|---|---|
api_keys_list | List API keys for this tenant. | settings.manage_api_keys |
api_keys_create | Generate a new API key. | settings.manage_api_keys |
api_keys_revoke | Revoke an API key by ID. | settings.manage_api_keys |
api_keys_delete | Permanently delete an API key (revoke it first to keep an audit trail of the key row). | settings.manage_api_keys |
Observability
| Tool | What it does | Permission |
|---|---|---|
events_list | Read the unified event stream: workflow runs and step logs, integration calls, agent runs, task lifecycle, system jobs, and (with settings.view) audit and security events. | observability.view |
integration_calls_list | List outbound integration API calls captured by the reference executor. | integrations.view |
integration_calls_get | Get a single integration call log with the full request body, response body, and headers (sensitive values redacted). | integrations.view |
agent_runs_list | List agent execution runs. | agents.view |
agent_runs_get | Get a single agent run with the full conversation (input message, output response), tool_calls array, and token breakdown. | agents.view |
object_audit_log_query | Query the unified object audit log — every create, update, delete, publish, toggle, and configuration change across the platform. | settings.view |
trace_get | Get all entities that share a single trace_id — the full call graph for a workflow execution. | workflows.view_runs |
Decision tables
| Tool | What it does | Permission |
|---|---|---|
decision_tables_list | List business rules / decision tables. | workflows.view |
decision_tables_get | Get a single decision table with inputs, outputs, rules, and metadata. | workflows.view |
decision_tables_export | Export a decision table as portable JSON so MCP can clone, version, or recreate the rule asset in another tenant. | workflows.view |
decision_tables_create | Create a business rule / decision table with custom inputs, outputs, and ordered rules. | workflows.create |
decision_tables_update | Update a decision table. | workflows.edit |
decision_tables_delete | Delete a decision table by ID (queued; workflows that call it will fail). | workflows.delete |
decision_tables_test | Test a decision table with sample input values and return the matched rule plus output payload. | workflows.view |
decision_tables_import | Import a decision table from portable JSON. | workflows.create |
Custom workflow steps
| Tool | What it does | Permission |
|---|---|---|
workflow_activities_list | List custom workflow activities available in Extensibility. | extensibility.view |
workflow_activities_get | Get a single custom workflow activity including source code, manifest, demo inputs, and metadata. | extensibility.view |
workflow_activities_export | Export a custom workflow activity as portable JSON so MCP can recreate the activity in another tenant or environment. | extensibility.view |
workflow_activities_create | Create a custom workflow activity asset. | extensibility.create |
workflow_activities_update | Update an existing custom workflow activity. | extensibility.edit |
workflow_activities_delete | Delete a custom workflow activity asset from Extensibility. | extensibility.delete |
workflow_activities_import | Import a portable custom workflow activity JSON export. | extensibility.create |
Email templates
| Tool | What it does | Permission |
|---|---|---|
email_templates_list | List email templates (name, subject, default flag). | workflows.view |
email_templates_get | Get an email template with its subject, HTML body and plain-text body. | workflows.view |
email_templates_create | Create an email template. | workflows.create |
email_templates_update | Update an email template. | workflows.edit |
email_templates_delete | Delete an email template. | workflows.edit |
email_templates_preview | Render an email template with sample variables using the same resolver as the send_email node. | workflows.view |
Retention
| Tool | What it does | Permission |
|---|---|---|
retention_policies_list | List and search centrally governed retention policies, optionally filtering by scope or policy mode so MCP can discover reusable governance rules for tables/lists, rows, and roles. | settings.view |
retention_policies_list_assets | List which tables, rows, and roles currently use a retention policy so MCP can assess governance coverage and cleanly plan updates or deletions. | settings.view |
retention_policies_get | Get a single retention policy by ID so MCP can inspect exact retention behavior before assignment or reuse. | settings.view |
retention_policies_create | Create a centrally governed retention policy that can later be assigned to tables/lists, individual rows, and roles. | settings.edit |
retention_policies_update | Update a centrally governed retention policy, including its mode, timing, description, and allowed scopes. | settings.edit |
retention_policies_delete | Delete a retention policy after confirming it is no longer assigned to any tables, rows, or roles. | settings.edit |
retention_policies_assign | Assign or clear a centrally governed retention policy on a table/list, individual row, or role. | settings.edit |
Webhooks
| Tool | What it does | Permission |
|---|---|---|
webhooks_list | List the inbound webhooks of a workflow (slug, inbound url, active flag, payload mapping, receive count). | settings.manage_webhooks |
webhooks_get | Get one inbound webhook (the secret is never returned). | settings.manage_webhooks |
webhooks_create | Create an inbound webhook that starts the workflow. | settings.manage_webhooks |
webhooks_update | Change a webhook slug, payload mapping or active flag. | settings.manage_webhooks |
webhooks_delete | Delete an inbound webhook; its url stops working. | settings.manage_webhooks |
webhooks_rotate | Replace a webhook secret (the old one stops working). | settings.manage_webhooks |
Log destinations
| Tool | What it does | Permission |
|---|---|---|
log_destinations_list | List log export destinations (Splunk HEC, Datadog, OTLP/HTTP, webhook, syslog, Azure Monitor, Event Hubs, Cloud Logging, Pub/Sub) with status and cursor. | observability.view |
log_destinations_get | Get one log export destination (credentials masked as __SECRET__). | observability.view |
log_destinations_status | Delivery status of a log export destination: cursor, lag (events and seconds), events sent, last success and last error. | observability.view |
log_destinations_create | Create a log export destination that ships the event stream to Splunk HEC, Datadog Logs, an OpenTelemetry collector (OTLP/HTTP), an HTTPS webhook, a syslog receiver (RFC 5424 over TLS), Azure Monitor (Logs Ingestion API… | settings.edit |
log_destinations_update | Update a log export destination. | settings.edit |
log_destinations_delete | Delete a log export destination (shipping stops; already delivered events are unaffected). | settings.edit |
log_destinations_reset_cursor | Move a destination's cursor: "now" skips the unsent backlog, "retention_start" re-sends every event still retained. | settings.edit |
log_destinations_test | Send one synthetic system.test event to a log export destination through the real formatter and connection; returns ok, HTTP status code, latency and the (redacted) error. | settings.edit |
directory_sync
| Tool | What it does | Permission |
|---|---|---|
directory_sync_list | List directory connections (Entra ID, Okta, LDAP / Active Directory, Google Workspace, SCIM) with sync state, linked user/group counts and the SCIM base URL. | settings.view |
directory_sync_get | Get one directory connection (settings, masked credentials, sync state). | settings.view |
directory_sync_connect | Connect a directory. | settings.edit |
directory_sync_update | Update a directory connection: settings and credentials merge over the stored ones (null removes a key, __SECRET__ keeps a secret); re-verified when they change. | settings.edit |
directory_sync_disconnect | Disconnect a directory: syncing stops and credentials are removed (SCIM: every token is revoked). | settings.edit |
directory_sync_test | Test a directory connection, optionally with unsaved settings/credentials merged over the stored ones. | settings.edit |
directory_sync_start | Start a directory sync run now (background). | settings.edit |
directory_sync_runs_list | List directory sync runs, newest first, with status, mode (full/delta), stats and errors. | settings.view |
scim_tokens_list | List SCIM tokens (name, prefix, scopes, last use, expiry) — never the tokens themselves. | settings.view |
scim_tokens_create | Create a SCIM bearer token for an identity provider (returned once) and enable SCIM provisioning. | settings.edit |
scim_tokens_rotate | Replace a SCIM token with a new one (same name and scopes, returned once); the old one stops working now or after grace_minutes. | settings.edit |
scim_tokens_delete | Revoke and delete a SCIM token. | settings.edit |
Workspace theme
| Tool | What it does | Permission |
|---|---|---|
workspace_theme_get | Get the workspace theme every member sees (colours for light and dark, fonts, shape, density, sidebar/topbar style, logos), its version and any WCAG contrast warnings. | tasks.view_own |
workspace_theme_presets_list | List the built-in theme templates (id, name, description, category and a few colours per mode). | tasks.view_own |
workspace_theme_update | Replace the workspace theme. | settings.edit |
workspace_theme_apply_preset | Replace the workspace theme with a built-in template (see workspace_theme_presets_list). | settings.edit |
workspace_theme_font_upload | Upload a woff2 font (base64, at most 1 MB) to the workspace brand-fonts folder. | settings.edit |
config
| Tool | What it does | Permission |
|---|---|---|
config_export | Export workspace configuration as one portable manifest (config as code). | tasks.view_own |
config_apply | Apply a config manifest (from config_export or a config-as-code folder) to this workspace: creates or updates, never deletes. | tasks.view_own |
packages
| Tool | What it does | Permission |
|---|---|---|
packages_list | List packages authored in this workspace (bundles of a process: workflows and everything they use, built into signed .utpkg files). | packages.view |
packages_get | Get a package (by id or slug) and its recent versions. | packages.view |
packages_preview | Preview what a package of these root artifacts would contain: dependencies (and why each is included), data tables, and the requirements an install will ask for (credentials, environment URLs, assignees). | packages.view |
packages_create | Create a package from root artifacts; dependencies are included automatically. | packages.manage |
packages_update | Update a package: metadata, add / remove artifacts, data modes. | packages.manage |
packages_delete | Delete a package and its built versions (installs in other workspaces are unaffected). | packages.manage |
packages_contents | What a package contains now: artifacts with the reason each is included, data modes and requirements. | packages.view |
packages_versions_list | List built versions of a package. | packages.view |
packages_build | Build, sign and publish a new version of a package (version, or bump the latest: patch by default). | packages.manage |
packages_version_get | Get one built version (manifest: requirements, files, checksum, signature). | packages.view |
packages_download | Download a built version as base64 .utpkg. | packages.view |
packages_inspect | Verify a .utpkg (checksum, file hashes, signature and signer trust) and list its assets, data, requirements and dependencies. | packages.view |
packages_installs_list | The package library: installed packages with version, source, signer and status (complete / incomplete). | packages.view |
packages_installs_get | An installed package: requirement checklist (what still needs configuration) and installed assets. | packages.view |
packages_install_plan | Dry run of installing or upgrading a package: per-asset create / update / unchanged with diffs, requirements (met / missing), data rows, dependencies and blockers. | packages.view |
packages_install | Install a package, or upgrade it in place when installed already (local credentials are kept). | packages.install |
packages_upgrade | Upgrade an installed package to the version in the file (dry_run shows the diff first). | packages.install |
packages_complete_setup | Complete setup of an incomplete install: supply the missing requirement values; the assets they unblock are enabled and its workflows activated. | packages.install |
packages_uninstall | Uninstall a package: removes its assets. | packages.install |
packages_history | Package history, newest first: every install, upgrade, reinstall, downgrade, reconfigure (complete setup) and uninstall, failed attempts included — who, when, channel, version from → to, signature status, counts, requir… | packages.view |
packages_history_get | One package history event with the full plan / diff that was applied (secrets masked). | packages.view |