Connect an AI Assistant

Truetask has a built-in MCP server that lets AI assistants like Claude, ChatGPT, Gemini, and LM Studio read and manage your boards directly. Once connected, you can ask them to create tasks, update checklists, search your data, and more — without copy-pasting.

All communication goes through your own Truetask instance. Your data never leaves your server.

What You Can Do Once Connected

Once an AI is connected, it can:

• Read your boards — lists, cards, members, tags, custom fields
• Create and update tasks — assign members, set priorities, manage dates
• Work with checklists — add items, check them off, reorder
• Search — across tasks, boards, comments, tags, and checklists
• Track time — start / stop timers, log manual entries
• Manage automations — create, import, and export workflow automations
• Organize — create folders and templates, clone boards

Getting Started

The fastest path is the built-in setup wizard.

From the app

1. Click your profile avatar (top-right) and select AI Assistant
2. The wizard asks which AI tool you're using
3. It creates an API key and shows you the exact configuration to paste
4. Paste the configuration into your AI tool and restart it

No manual setup required.

Supported tools

Tool	Where the config goes
Claude Code	.mcp.json in your project folder
Claude Desktop	claude_desktop_config.json (edit via Settings → Developer → Edit Config)
ChatGPT	Settings → Beta features → MCP Servers
Gemini	Settings → Extensions → MCP Servers
LM Studio	Tools → MCP Servers
Other MCP clients	Use the HTTP endpoint directly (see Manual Configuration)

API Keys

API keys control what your AI assistant can do. Create and manage them from the AI Assistant dialog (profile menu) or Settings → API & Webhooks → API Tokens.

Scopes

Scope	What it allows
Read & Write	Full access — read, create, update, delete tasks, comments, time entries, etc. The default for most use cases.
Read Only	List and view data, but no modifications. Good for dashboards or pure query assistants.

Key format

Every API key starts with tt_ followed by a long random string:

tt_874bb0d07566b19f1d5635bc3d32d146f7ba591755235064d83b63ad418de21b

Keys are shown only once

When you create a key, the full value is displayed once. Save it somewhere secure — you can't view it again, only revoke and create a new one.

Expiration

Keys don't expire by default. You can optionally set an expiration date when creating a key. Expired keys stop working immediately.

Revoking a key

Open the AI Assistant dialog, find the key, and click the delete icon. Revocation takes effect immediately.

Manual Configuration

If you prefer to configure manually, here are the formats for each tool.

Claude (Code and Desktop)

{
  "mcpServers": {
    "truetask": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-server/mcp",
        "--header",
        "Authorization: Bearer ${TRUETASK_KEY}"
      ],
      "env": {
        "TRUETASK_KEY": "tt_your_key_here"
      }
    }
  }
}

• Claude Code — save as .mcp.json in your project root
• Claude Desktop — paste into claude_desktop_config.json

ChatGPT

Same format as Claude. Paste into Settings → Beta features → MCP Servers.

Gemini

{
  "mcpServers": {
    "truetask": {
      "httpUrl": "https://your-server/mcp",
      "headers": {
        "Authorization": "Bearer tt_your_key_here"
      }
    }
  }
}

LM Studio

{
  "mcpServers": {
    "truetask": {
      "url": "https://your-server/mcp",
      "headers": {
        "Authorization": "Bearer tt_your_key_here"
      }
    }
  }
}

Generic HTTP Clients

Use the HTTP endpoint directly:

URL:    https://your-server/mcp
SSE:    https://your-server/mcp/sse
Header: Authorization: Bearer tt_your_key_here

Both Streamable HTTP (/mcp) and Server-Sent Events (/mcp/sse) are supported. Streamable HTTP is the recommended transport.

Available Tools

Connected AI assistants have access to dozens of tools organized by category.

Tool names follow <resource>_<action> so they group alphabetically by surface (cards_list, cards_create, cards_bulk_update, etc.). If you're upgrading from a pre-rename setup, see the Migration: Renamed Tools table at the bottom of this section.

Boards and Lists

Tool	Description
boards_list	List all boards you're a member of
boards_get	Board details with members
boards_create	Create a board with default or custom lists
boards_update	Change name, status, or AI context
boards_clone	Copy a board's structure (without tasks)
boards_delete	Delete a board (requires confirmation)
lists_list / lists_create / lists_update / lists_delete	Manage lists

Tasks

Tool	Description
cards_list	List tasks with optional filters
cards_get	Full task details
cards_create	Create a new task. Pass draft=true to create it as a private draft visible only to you
cards_bulk_create	Create many tasks on the same board in one call. Returns per-item success/failure
cards_update	Update any task field. Pass draft=false on a draft to publish it to the whole board
cards_move	Move a task between lists
cards_complete	Mark complete and move to done
cards_delete	Move a task to the board's trash. Pass permanent=true to skip the trash and delete immediately (board admins only).
cards_restore	Restore a trashed or archived task to its original list
cards_list_trashed	List tasks currently in a board's trash, including their remaining retention window
cards_bulk_update	Apply the same change to many tasks

Checklists

Tool	Description
checklists_list	List checklist items on a task
checklists_create	Add an item
checklists_bulk_create	Add many items across one or more tasks in a single call
checklists_update	Check off or edit
checklists_delete	Remove

Comments

Tool	Description
comments_list / comments_create / comments_update / comments_delete	Manage comments on a task
comments_bulk_create	Post many comments across one or more tasks in a single call

Tags and Custom Fields

Tool	Description
tags_list / tags_create	Manage tags
xattr_fields_list / xattr_fields_create	Manage custom field definitions
xattr_values_list	List a single card's custom field values
xattr_values_list_for_board	List custom field values across every card on a board (optionally filtered to one field). Useful for cross-card analysis like "average story points this sprint"
xattr_values_create	Set a custom field value on a task

Time Tracking

Tool	Description
timer_start / timer_stop	Control the running timer
time_entries_create	Manually log a time entry
time_entries_list	List time entries with optional filters: task (one card), board_id (all cards on a board), since / until (ISO date range). Useful for burndown, weekly reports, and similar-card estimates

Search

Tool	Description
search	Query across tasks, boards, comments, tags, and checklists

Organization

Tool	Description
folders_list / folders_create	Manage folders
users_list / users_me	User info (for assigning members)
groups_list	User groups

Automations

Tool	Description
automations_list / automations_create	Manage automations
automations_export / automations_import	Portable JSON exchange
automations_get_logs	View execution history

Templates

Tool	Description
templates_list	List board templates
templates_create_from_board	Save a board as a template
boards_create_from_template	Create a board from a template

Migration: Renamed Tools

If your AI assistant or scripts reference the older <verb>_<noun> tool names, the table below maps each old name to its current <resource>_<action> replacement. There are no aliases — the old names no longer resolve.

Old name	New name		Old name	New name
list_boards	boards_list		list_xattr_fields	xattr_fields_list
get_board	boards_get		get_xattr_field	xattr_fields_get
create_board	boards_create		create_xattr_field	xattr_fields_create
update_board	boards_update		update_xattr_field	xattr_fields_update
clone_board	boards_clone		delete_xattr_field	xattr_fields_delete
delete_board	boards_delete		list_xattr_values	xattr_values_list
create_board_from_template	boards_create_from_template		list_xattr_values_for_board	xattr_values_list_for_board
list_lists	lists_list		get_xattr_value	xattr_values_get
get_list	lists_get		create_xattr_value	xattr_values_create
create_list	lists_create		update_xattr_value	xattr_values_update
update_list	lists_update		delete_xattr_value	xattr_values_delete
delete_list	lists_delete		list_templates	templates_list
list_cards	cards_list		get_template	templates_get
get_card	cards_get		create_template_from_board	templates_create_from_board
create_card	cards_create		delete_template	templates_delete
update_card	cards_update		list_saved_filters	saved_filters_list
move_card	cards_move		get_saved_filter	saved_filters_get
complete_card	cards_complete		create_saved_filter	saved_filters_create
delete_card	cards_delete		update_saved_filter	saved_filters_update
restore_card	cards_restore		delete_saved_filter	saved_filters_delete
list_trashed_cards	cards_list_trashed		list_automations	automations_list
bulk_update_cards	cards_bulk_update		get_automation	automations_get
bulk_manage_members	cards_bulk_manage_members		create_automation	automations_create
bulk_manage_tags	cards_bulk_manage_tags		update_automation	automations_update
bulk_move_cards	cards_bulk_move		delete_automation	automations_delete
bulk_complete_cards	cards_bulk_complete		get_automation_logs	automations_get_logs
bulk_archive_cards	cards_bulk_archive		export_automation	automations_export
bulk_set_priority	cards_bulk_set_priority		import_automation	automations_import
bulk_create_cards	cards_bulk_create		trigger_automation	automations_trigger
list_tags	tags_list		list_my_board_subscriptions	subscriptions_list
get_tag	tags_get		get_my_board_subscription	subscriptions_get
create_tag	tags_create		subscribe_to_board	subscriptions_create
update_tag	tags_update		unsubscribe_from_board	subscriptions_delete
delete_tag	tags_delete		export_workspace	workspace_export
list_priorities	priorities_list		list_milestones	milestones_list
get_priority	priorities_get		get_milestone	milestones_get
list_checklists	checklists_list		create_milestone	milestones_create
get_checklist_item	checklists_get		update_milestone	milestones_update
create_checklist_item	checklists_create		delete_milestone	milestones_delete
update_checklist_item	checklists_update		list_files	files_list
delete_checklist_item	checklists_delete		get_file	files_get
bulk_create_checklist_items	checklists_bulk_create		delete_file	files_delete
list_comments	comments_list		list_folders	folders_list
get_comment	comments_get		get_folder	folders_get
add_comment	comments_create		create_folder	folders_create
update_comment	comments_update		update_folder	folders_update
delete_comment	comments_delete		delete_folder	folders_delete
bulk_add_comments	comments_bulk_create		get_me	users_me
list_dependencies	dependencies_list		list_users	users_list
add_dependency	dependencies_create		get_user	users_get
remove_dependency	dependencies_delete		list_groups	groups_list
start_timer	timer_start		get_group	groups_get
stop_timer	timer_stop		create_group	groups_create
list_time_entries	time_entries_list		update_group	groups_update
get_time_entry	time_entries_get		delete_group	groups_delete
create_time_entry	time_entries_create		search	search (unchanged)
update_time_entry	time_entries_update
delete_time_entry	time_entries_delete

Safety Guardrails

Destructive operations include built-in safety checks:

• Deleting boards, lists, folders, or groups requires a confirm=True parameter. Without it, the tool returns a preview of what would be affected — nothing is deleted.
• Deleting tasks is recoverable by default — cards_delete moves the task to the board's trash, where it stays for the configured retention period (30 days by default). Use cards_restore to bring it back. To permanently delete immediately, pass permanent=True (board admins only).
• Low-impact deletes (comments, tags, checklist items, time entries) execute directly.
• The last done list on a board can't be deleted or changed to "open" — every board must have at least one done list.

These guardrails are baked in — the AI can't bypass them even if it tries.

Troubleshooting

The AI can't connect

• Make sure your Truetask instance is reachable from the machine running the AI tool
• Check that the API key starts with tt_ and hasn't expired
• Verify the URL points to your Truetask instance (e.g. https://truetask.yourcompany.com/mcp)

The AI says "unauthorized"

• Your API key may have been revoked — create a new one
• If the AI needs to manage groups, it requires an admin-scope key (created from Settings → API & Webhooks)

Tools aren't showing up

• Restart your AI tool after adding the configuration
• For Claude Code, make sure .mcp.json is in the root of your current project
• For Claude Desktop, make sure you edited the correct config file (not a test copy)

Performance

• The MCP server uses the same authentication and rate limits as the REST API — see API & Webhooks for specifics
• For very large boards, the AI may paginate through results automatically

What's Next?

• API & Webhooks — the underlying REST API
• Automations — automate board events (no AI required)