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 runs on Vercel and uses SSE (Server-Sent Events) transport. The endpoint is:

https://mcp.hypertask.ai/sse

Endpoints

Once connected, the following endpoints are available:

Endpoint	Type	Description
/mcp	Streamable HTTP	Primary MCP communications via HTTP streaming
/sse	SSE	Server-Sent Events endpoint connected to /message
/message	SSE	Redis-backed event stream for real-time state updates
/openapi.json	OpenAPI schema	Auto-generated OpenAPI spec for ChatGPT and other clients
/health	HTTP	Health check endpoint
/	HTTP	Root 307 redirect to the main app for OAuth flows

AI Assistant Self-Onboarding

Memorystore apps and public marketing pages on hypertask.ai can automatically discover the MCP server address by opening the llms.txt file:

https://hypertask.ai/llms.txt
https://app.hypertask.ai/llms.txt
https://mcp.hypertask.ai/llms.txt

The file returns a human-readable instructions block that includes:

• Connect-An-AI-Assistant block with instructions and steps for Claude, ChatGPT, Claude Code, and CLI environments
• MCP endpoint URL (https://mcp.hypertask.ai/sse) for direct connection
• Authentication instructions using JWT bearer tokens

This enables AI assistants to self-discover and connect to Hypertask without manual configuration. For environments that support llms.txt parsing (such as Claude Desktop and ChatGPT’s current and future releases), the protocol automatically applies the connection details.

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 one 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.

Agent identity

You can manage agents as service accounts with scoped API keys. Configure agents to:

• Create and rotate API keys via MCP
• Restrict keys with project-level and model-level scopes
• Display a bot badge in UI and in MCP tool metadata

This makes each agent behave like a dedicated account with its own permission profile. Agents can be created, updated, or deactivated via MCP, and their scoped keys are scoped to the scopes they were assigned.

Persistent Speed Engineer

On board 15, the Speed Engineer now runs in a brokered pattern. Its sessions are backed by a persistent worker that pulls capability from a localhost broker using a short-lived ticket/cycle. This isolates managed tokens and prevents direct access to credential files or unmanaged token usage. For board-15 task cycles, use the standard lease-based claim/heartbeat/release workflow shown in Agent Workflows; the agent identity itself remains scoped and the broker ensures it cannot read your credential files directly.

Expose board AI custom instructions over MCP

In addition to skills and playbooks, you can manage board AI custom instructions directly from MCP:

• GET /api/mcp/projects/[projectId]/instructions — Retrieve the currently configured board-level custom instructions.
• PUT /api/mcp/projects/[projectId]/instructions — Update or reset the board AI custom instructions.

This complements the MCP-exposed skills and playbooks, giving agents full control over board-level AI behavior without needing to navigate to the UI.

Provide agent lease heartbeats

Agents can safely claim, heartbeat, and release tasks via dedicated endpoints under /api/mcp/tasks/lease/:

• POST /api/mcp/tasks/lease/claim — Claim an available task for handling.
• POST /api/mcp/tasks/lease/heartbeat — Broadcast ongoing work (heartbeats) to keep the lease alive.
• POST /api/mcp/tasks/lease/release — Release a claimed task so others can pick it up.

These endpoints allow agents to coordinate worker pools without races, supporting multi-agent workflows and shared task queues.

Re-enabling external agents mint fresh MCP credentials

When you turn an agent back on, Hypertask mint a fresh MCP credential for it if the agent has none:

• The API returns hasMcpToken: true for an active external agent in agent detail responses, and shows no raw mcpToken field.
• A copyable configuration is shown once so the UI cannot claim an unusable agent is active.
• Old credentials remain revoked; new credentials are used for authenticating via MCP.
• Owners-only agents and external agents both receive this behavior, ensuring credentials are always available on re-enable.

Move tasks to inbox via MCP

You can now trigger tasks to move to your inbox programmatically:

• Move task to inbox — Takes a task identifier (ID or uniqueIndex) and marks the task as unread, clearing any existing folder, adding it to the Inbox section, and resetting the priority to high.
• Available via MCP tools and the CLI, enabling agents and workflows to reactively route high-priority work into your inbox.

Agent-tier rate limits

Authenticated agent tokens that carry valid htk_ API keys receive a higher rate-limit tier:

• Base: 120 requests/minute for unauthenticated or invalid keys
• Agent-tier: 600 requests/minute for authenticated agents with valid htk_ keys

This mode specifically applies to agent traffic; non-agent traffic remains subject to the base limits. Agent-tier tokens are detected via the Authorization header that must include a valid Hypertask API key.

Full capability parity across surfaces

The MCP server now exposes 81 of 96 core capabilities across the API, CLI, AI Chat, and HyperAI. New and extended tools match REST endpoint behavior for board configuration, project administration, profile updates, page history, task description history, and relations composition. All tools are thin wrappers over the same REST routes that power the web UI, ensuring consistent behavior regardless of which surface you use.

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"
      }
    }
  }
}

ChatGPT

Hypertask exposes an OpenAPI schema that ChatGPT can consume as a custom action or GPT integration. This lets ChatGPT create tasks, list projects, search tickets, and more — without needing native MCP support.

1. In ChatGPT, open My GPTs (or the GPT editor for a custom GPT you control).
2. Go to Actions — Add action.
3. Import the Hypertask OpenAPI schema from:

   https://mcp.hypertask.ai/openapi.json

4. Under Authentication, choose API Key and paste your Hypertask API key (the same token you use for MCP). Set the header name to Authorization and the value format to Bearer YOUR_API_KEY.
5. Save the action. ChatGPT will now list the available Hypertask operations and can call them on your behalf.

Tip

The OpenAPI schema is auto-generated from the same endpoints that power the MCP server, so it always stays in sync with the latest tools. Any new MCP tool automatically appears as an available action in ChatGPT.

AI Chat integration

AI Chat exposes equivalents for most MCP operations and shares the same assignment behavior layer. Its tool definitions are maintained separately, so each new MCP parameter still needs an AI Chat adapter when the input shape differs.

AI Chat reads and writes, and it is not a reduced version of MCP. It manages tasks, comments, drafts, pages, labels, views, skills, sections, timers and task relations, assigns people or board agents, moves tasks between boards and to the inbox, reads board manifests and playbooks, checks agent presence, and raises decision requests. Its hypertask_update_task is the richest of any surface: it alone adds or removes a single label without replacing the rest, and writes to several tasks in one call.

For assignment and unassignment, AI Chat accepts a person’s user ID, me, display name, or email. It also accepts a board agent’s display name or UUID. Agent matching is case-insensitive and board-scoped; a person-agent name collision returns an explicit ambiguity error.

Only two MCP tools have no AI Chat equivalent, and neither is a capability gap: hypertask_hello (the connection-time onboarding map, which the chat gets from its system prompt) and the report action of hypertask_time.

Some capabilities are shared but named differently. MCP folds comment edits into hypertask_add_comment_to_task, unassign into hypertask_assign_user, and every timer action into hypertask_time, where AI Chat gives each its own tool.

AI Chat also has three tools no other surface has: search_help_docs, rag_retrieval over indexed board content, and web_search.

Help-site AI chat

The help-site AI chat at help.hypertask.ai provides real-time documentation and MCP guidance. This chat is automatically enriched with Hypertask’s MCP server knowledge, including tool descriptions, schemas, and workflows.

Knowledge coverage

• MCP tools: Instant understanding of all MCP operations (tools, parameters)
• Workflow patterns: Guidance from MCP agent workflows (e.g. safe task claiming, heartbeat loops)
• API schemas: Embeds OpenAPI specs and model responses to answer “what can I call with these parameters?”
• Board content: RAG-based retrieval over indexed tasks, comments, and pages for contextual answers

Performance

• Model: google/gemini-3.5-flash-lite via the Vercel AI Gateway
• Streaming: Real-time tokens around 0.3s to first token
• Multimodal: Text and image questions in a single model

Try it

# Ask about tools
"which MCP tools exist for time tracking?"

# Ask about workflows
"how should an agent claim a task and keep it alive?"

# Ask about a specific endpoint
"show me the hypertask_create_task tool schema"

Retrieval

The chat uses keyword scoring instead of first-come fill, so contextual terms like “cli”, “mcp”, and “task” score accurately. Answers link to specific MCP tools, API endpoints, and board content.

---

Known limitations

Feature	Status	Details
@mentions in comments	Partial	The mentions parameter on hypertask_add_comment_to_task works, but mentions can render as plain text without firing a notification. Pass structured mention objects (user_id + display_name) for reliable results.
Auto-linking ticket references	Not supported	A ticket reference such as HTPR-1234 inside a comment posted over MCP is not turned into a related-task link the way the web UI does it. Call hypertask_link_tasks to create the relation explicitly.
Pages and description history	REST only	Version listing and restore for pages and task descriptions exist at /api/mcp/pages/versions, /pages/restore, /tasks/description-versions and /tasks/description-restore, but have no MCP tool yet.
Agent infrastructure	REST only, by design	Task leases, evidence, escalation, work sessions, service-account management, API keys and webhooks are REST endpoints only. They are plumbing for autonomous workers rather than things an assistant should call mid-conversation.

Note

Creating labels and managing saved views used to be listed here as unsupported. Both work now, from every surface: hypertask_create_label, and the full hypertask_create_view / update_view / delete_view / switch_view set.

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, and ChatGPT via the OpenAPI adapter:

• Claude Code — Anthropic’s CLI agent
• Claude Desktop — Anthropic’s desktop app
• Cursor — AI-powered code editor
• Windsurf — Codeium’s AI editor
• ChatGPT — via the Hypertask OpenAPI schema (custom actions / GPTs)
• 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 tools, including time tools.