Taskpile.app

Taskpile MCP

Public documentation for Taskpile's Model Context Protocol server.

Never forget a thing. Stay focused on today. Taskpile is a personal task tracker built around two verbs: pile in, sort out. Capture anything the moment it shows up, from Claude, ChatGPT or any MCP-compatible client, or in the app at taskpile.app. A two-minute daily review turns the pile into one short Today list; everything else waits its turn.

Taskpile is listed in the Claude connectors directory.

• App: https://taskpile.app
• MCP endpoint: https://taskpile.app/api/mcp
• Transport: Streamable HTTP (JSON-RPC 2.0)
• Protocol versions supported: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05

This repository contains only public-facing documentation for the MCP integration. The Taskpile app itself is a hosted commercial product: its source isn't here, but everything you need to connect a client and use the MCP tools is.

Connecting

Any MCP-compatible client can connect by pointing at the URL above. Authentication uses OAuth 2.1 with Dynamic Client Registration + PKCE. The client handles this automatically; users sign in to Taskpile in a browser tab when prompted.

Verified clients:

Client	Status
Claude.ai (Connectors)	✅
Claude Desktop (via mcp-remote)	✅
Claude Code	✅
ChatGPT (Connectors)	✅
Le Chat (Mistral)	✅
Cursor	✅
Zed	✅
MCP Inspector	✅
Lovable.app	✅

Quick start by client

See examples/ for ready-to-paste config snippets:

• Claude Desktop
• Cursor
• Cline (VS Code)
• MCP Inspector

For hosted clients like Claude.ai and ChatGPT, add Taskpile via their built-in connector UI and paste the URL above; no local config needed.

Tools

Taskpile exposes 72 tools spanning task CRUD, projects, tags, colors, search, bulk operations, teams, and account integrations like morning digest and task reminders. The full machine-readable schema (names, descriptions, JSON Schema for inputs and outputs) is in tools.json, generated from the server's tool schema.

tools/list is tailored to the account, so a client usually sees fewer than 72: team administration tools appear once the user belongs to a team, project-member tools once they have a shared project, assignment/triage tools once they can reach a team-owned project, and search/fetch only for OpenAI clients. Hidden tools stay callable; the entry points (create_team, convert_project_to_shared, invite_to_project, list_received_invitations, accept_invitation) are always listed.

A quick taste:

• create_task, list_tasks, update_task, complete_task, delete_task
• assign_horizon (today_morning, tomorrow, next_week, etc.), delegate_task, set_recurrence
• list_projects, create_project, archive_project
• search_tasks (free-text + status/horizon filters)
• bulk_complete, bulk_archive (reversible, prefer it over bulk_delete), bulk_delete, bulk_assign_horizon (up to 200 ids per call)
• changes_since (incremental sync: deletions are not reported, so reconcile with a full fetch periodically; capped at 500 rows per call), get_today, get_review_queue
• list_closed_tasks (what got completed in a date range)
• get_morning_digest, configure_morning_digest, get_task_reminders, configure_task_reminders
• list_colors, create_color, update_color, delete_color
• whoami, get_inbox_email
• Teams: create_team, invite_to_team, accept_invitation, assign_task, convert_project_to_shared, etc.
• search and fetch (ChatGPT Connectors built-in tools, mapped to Taskpile)

Conventions

A few project-wide conventions worth knowing if you're writing a prompt:

• Tags use @tag_name. Projects use #project_name. Do NOT use # for tags: #foo is silently treated as a project name.
• create_task parses #project and @tag shorthand from the title. Only the FIRST # token becomes the project; the rest are stripped.
• #name resolution covers projects shared with you, not just your own. If the name is unique it's used; if it's ambiguous (e.g. a private AND a shared project with the same name) the call fails with a candidate list: ask the user which, then retry with an explicit projectId. If nothing matches, a new project you own is created.
• To set tags at creation, pass tags: string[] and/or put @tag in the title. Both forms work and are de-duplicated.
• update_task does not parse #/@ shorthand from the title. Use tags / addTags / removeTags and projectId to change those.
• Prefer dedicated verbs over update_task when they exist: complete_task, assign_horizon, delegate_task.
• Bulk endpoints accept up to 200 ids per call.

Auth flow

If you're building a client and want to know what to expect:

1. Client sends an unauthenticated request to https://taskpile.app/api/mcp and receives 401 with WWW-Authenticate: Bearer realm="taskpile", resource_metadata="https://taskpile.app/.well-known/oauth-protected-resource".
2. Client fetches https://taskpile.app/.well-known/oauth-protected-resource and …/oauth-authorization-server to discover endpoints.
3. Client POSTs to https://taskpile.app/oauth/register for Dynamic Client Registration (RFC 7591).
4. Client kicks off the standard authorization-code + PKCE flow, opens a browser at /oauth/authorize, exchanges the code at /oauth/token, and receives an access_token.
5. Subsequent requests carry Authorization: Bearer <token>. Access tokens are valid for 30 days. A client that registers the refresh_token grant also gets a refresh token, valid for 90 days and rotated on every use; other clients re-run the authorize/token flow on expiry. Tokens can be revoked at /oauth/revoke (RFC 7009).

HEAD /api/mcp returns 200 without auth and is intended for liveness probes only.

Privacy + data handling

• Taskpile is GDPR-compliant. Tasks, projects, and tags created via MCP are user-owned and visible only to the authenticated user (and their team members for shared projects).
• The MCP integration sends task content to Taskpile's servers (EU-hosted). It does NOT route through Anthropic, OpenAI, or any other LLM provider: those are clients of the MCP server, not the server itself.
• Personal access tokens can be created in Taskpile → Settings → Integrations and revoked at any time.

Issues and feedback

This repo is for documentation. Bug reports about the MCP server, feature requests for new tools, or questions about the API: please open an issue here and we'll triage.

For Taskpile app issues (unrelated to MCP), please contact us through the app at https://taskpile.app.

License

Documentation in this repository is MIT-licensed (see LICENSE). The Taskpile app itself is a hosted commercial product and is not licensed for redistribution.