MCP Integration

Hypertask provides a full Model Context Protocol (MCP) server that lets AI agents create, update, search, and manage tasks programmatically. Any MCP-compatible client can connect to Hypertask and operate as an autonomous worker.

What is MCP?

The Model Context Protocol is an open standard that defines how AI models interact with external tools and data sources. Instead of building custom integrations for each AI client, Hypertask exposes a single MCP server that works with all of them.

MCP uses a tool-based architecture: the server advertises available operations (list tasks, create task, add comment, etc.) and the AI client calls them as needed to complete user requests.

Transport

Hypertask’s MCP server uses SSE (Server-Sent Events) transport. The server endpoint is:

https://mcp.hypertask.ai/sse

Authentication

MCP connections are authenticated with JWT bearer tokens. To get your token:

1. Open app.hypertask.ai and sign in.
2. Go to Settings (gear icon in the sidebar).
3. Copy your API key from the MCP section.

Tip

You can also reach the MCP token dialog directly from the command palette: press Ctrl+K and search for MCP. The dialog includes a shortcut to the CLI install dialog if you want to set up the terminal CLI at the same time.

Caution

Tokens expire after 30 days. If your agent stops authenticating, generate a new token from Settings.

Agent bearer tokens

When an autonomous agent authenticates with its own bearer token (distinct from a human user’s token), all write operations â task creation, comment posting, assignments â are attributed to the agent itself, not to the agent’s owner. This means activity logs, notifications, and task histories correctly reflect the agent as the actor, making it straightforward to audit which agent made which change.

Client configuration

Claude Desktop

Add to your Claude Desktop config file (claude_desktop_config.json):

{
  "mcpServers": {
    "hypertasks": {
      "type": "sse",
      "url": "https://mcp.hypertask.ai/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Code

Add to your project’s .mcp.json or global ~/.claude/mcp.json:

{
  "mcpServers": {
    "hypertasks": {
      "type": "sse",
      "url": "https://mcp.hypertask.ai/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor

Open Settings > MCP Servers and add a new server:

{
  "mcpServers": {
    "hypertasks": {
      "type": "sse",
      "url": "https://mcp.hypertask.ai/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Available tools

Once connected, your agent has access to 16 tools:

Tool	Description
hypertask_get_user_context	Get current user info (id, email, display name)
hypertask_list_projects	List all accessible projects
hypertask_create_board	Create a new board with sections, labels, and starter tasks
hypertask_section	List or create sections on a board
hypertask_list_tasks	List tasks with filtering
hypertask_get_tasks	Get specific tasks by ID or ticket number
hypertask_search_tasks	Full-text search across all tasks
hypertask_create_task	Create a new task
hypertask_update_task	Update task fields
hypertask_move_task_between_boards	Move a task to another project
hypertask_assign_user	Assign or unassign users
hypertask_add_comment_to_task	Add a comment (HTML)
hypertask_get_comments_for_task	Read task comments
hypertask_list_project_members	List team members
hypertask_inbox_list	Check inbox notifications
hypertask_inbox_archive	Archive inbox items

AI Chat integration

New MCP tools and parameters are automatically available in AI Chat without any separate integration step. AI Chat uses the same underlying MCP tools as external agents, so its capabilities stay in sync with the MCP server as new tools are added.

Known limitations

The following features are not yet available via MCP:

Feature	Status	Details
Create labels	Not supported	You can assign existing labels to tasks, but cannot create new labels via MCP. Create labels in the Hypertask UI first, then reference them.
@mentions in comments	Partial	The mentions parameter on hypertask_add_comment_to_task is available, but mentions may appear as plain text and not trigger notifications. Use structured mention objects (user_id + display_name) for best results.
Related task linking	Not supported	Ticket references (e.g. HTPR-1234) in comments added via MCP are not automatically parsed into “related tasks” links like they are in the UI.
Saved views	Not supported	Saved views are accessible only from the web UI. MCP tools, CLI, and AI Chat do not currently support saved views.

Tip

For features not yet available via MCP, use the Hypertask CLI as a workaround â it supports labels, due dates, and description updates.

Troubleshooting

“Failed to Connect to MCP” â If your client cannot connect:

1. Verify your token has not expired (tokens expire after 30 days). Generate a new one from Settings in the Hypertask app.
2. Confirm the URL is exactly https://mcp.hypertask.ai/sse (including /sse).
3. Check that the Authorization header is formatted as Bearer <token> with a space after “Bearer”.
4. Restart your MCP client after updating the configuration.

Supported clients

Hypertask MCP works with any client that supports the MCP standard:

• Claude Code — Anthropic’s CLI agent
• Claude Desktop — Anthropic’s desktop app
• Cursor — AI-powered code editor
• Windsurf — Codeium’s AI editor
• Any MCP-compatible agent — anything that speaks the protocol

Next steps

CLI Reference Install the terminal CLI and manage tasks from your shell.

Agent Workflows Patterns for how AI agents should pick up and complete work.

MCP Tools Reference Complete parameter reference for all 16 tools.