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.

Boards and Lists

Tool	Description
list_boards	List all boards you're a member of
get_board	Board details with members
create_board	Create a board with default or custom lists
update_board	Change name, status, or AI context
clone_board	Copy a board's structure (without tasks)
delete_board	Delete a board (requires confirmation)
list_lists / create_list / update_list / delete_list	Manage lists

Tasks

Tool	Description
list_cards	List tasks with optional filters
get_card	Full task details
create_card	Create a new task
update_card	Update any task field
move_card	Move a task between lists
complete_card	Mark complete and move to done
delete_card	Permanently delete
bulk_update_cards	Apply the same change to many tasks

Checklists

Tool	Description
list_checklists	List checklist items on a task
create_checklist_item	Add an item
update_checklist_item	Check off or edit
delete_checklist_item	Remove

Comments

Tool	Description
list_comments / add_comment / update_comment / delete_comment	Manage comments on a task

Tags and Custom Fields

Tool	Description
list_tags / create_tag	Manage tags
list_xattr_fields / create_xattr_field	Manage custom field definitions
create_xattr_value	Set a custom field value on a task

Time Tracking

Tool	Description
start_timer / stop_timer	Control the running timer
create_time_entry	Manually log a time entry
list_time_entries	List time entries

Search

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

Organization

Tool	Description
list_folders / create_folder	Manage folders
list_users / get_me	User info (for assigning members)
list_groups	User groups

Automations

Tool	Description
list_automations / create_automation	Manage automations
export_automation / import_automation	Portable JSON exchange
get_automation_logs	View execution history

Templates

Tool	Description
list_templates	List board templates
create_template_from_board	Save a board as a template
create_board_from_template	Create a board from a template

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.
• Low-impact deletes (tasks, 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)