MCP connector

Two ways to authorize

Claude.ai (OAuth)

1. Open Customize → Connectors → + → Add custom connector.
2. Paste the URL https://taskid.app/mcp.
3. Press Add. Claude will open the Taskid authorization page.
4. Sign in (if you haven't already), pick the access level and lists.
5. After you confirm, the connector is ready - Claude will see your tasks.

Don't fill in OAuth Client ID / Secret in the advanced settings - Taskid uses Client ID Metadata Documents (CIMD) and Dynamic Client Registration, Claude picks everything up on its own.

ChatGPT (OAuth)

Requires a paid plan and Developer mode enabled. The plan determines access level:

• Plus / Pro - read-only (read / fetch).
• Business / Enterprise / Edu - full access, including writes.

Steps:

1. Enable Developer mode: Workspace Settings → Permissions & Roles → Connected Data → Developer mode (for Business/Enterprise) or in personal settings (Plus/Pro).
2. Go to Settings → Connectors (or Apps & Connectors) and click Create / Add new connector.
3. Name: Taskid, MCP Server URL: https://taskid.app/mcp.
4. Authentication: OAuth, tick I trust this application.
5. Save - the Taskid authorization window will open.

The URL must be HTTPS. Only add custom connectors after verifying that the server is safe (Taskid is open-source, the domain is TLS-verified).

Claude Desktop / Claude Code (Bearer)

Desktop and Code do not accept OAuth URLs through the UI yet. Use a REST API token tkd_... from the API tokens section:

claude mcp add --transport http taskid https://taskid.app/mcp \
  --header "Authorization: Bearer tkd_YOUR_TOKEN"

Verify: claude mcp list should show taskid ... ✓ Connected.

Codex CLI (Bearer)

For OpenAI Codex, pass the token through an environment variable - it is safer than keeping the secret directly in the config:

export TASKID_TOKEN='tkd_YOUR_TOKEN'

codex mcp add taskid \
  --url https://taskid.app/mcp \
  --bearer-token-env-var TASKID_TOKEN

Verify:

codex mcp list
codex mcp get taskid --json

The access scope (all lists / selected, read / write) is set when you create the token in settings.

What the connector can do

Shared lists

If a list has been shared with you (the "Share" button on the site), the connector sees it alongside your own. Every list comes with two extra fields:

• is_owner - true if you own the list; false if you're a member of someone else's.
• is_shared - true if the list has members (whether it's personal or shared).

A member can read the contents and create / edit / delete tasks and notes inside a shared list (including attaching files). The list itself (its name, icon, archival, deletion, moving into a group), however, can only be modified by the owner; a member's attempt will fail.

The fields completed_user_id and deleted_user_id on tasks show who actually closed / deleted the record - useful for auditing shared lists.

Files and links on tasks, notes and notifications

Every task, note and notification has a files array - the attached items. If nothing is attached, the array is empty. Each item:

{
  "id":     "9f1c-...",
  "name":   "contract.pdf",
  "size":   184320,
  "url":    "https://taskid.app/files/aa/bb/cc/9f1c....pdf",
  "source": "upload"           // 'upload' | 'link'
}

The source field distinguishes two types of attachments:

• "upload" - a file actually uploaded to our storage. url points to taskid.app and opens in a browser without authorization (a capability token is baked into the path). Counts against the user's file quota.
• "link" - an external HTTPS URL (our server doesn't download or store anything). url points to the third-party resource as-is. Does not count against the quota; size may be 0 if the resource server didn't return a size in the HEAD response on attach.

How to attach an uploaded file (two steps)

1. upload_file with fields name, mime_type, content_base64 - get the file.id. The file is not bound to anything on its own - if you don't attach it, orphan-sweep will delete it.
2. attach_file_to_task, attach_file_to_info or attach_file_to_notification with file_ids: ["..."] - attaches to the task / note / notification. The response is the updated record with the files array populated.

The file body is transmitted as base64 (not URL-safe, no data:... prefix). Size is limited by the user's quota; an oversized file returns an error.

How to attach an external URL (no upload)

If the resource is already accessible over HTTPS (image, dashboard, log, cloud document) there's no need to download and re-upload it. Use one of:

• attach_link_to_task
• attach_link_to_info
• attach_link_to_notification

The links parameter is an array of objects { url, name? }. The URL must be http/https; name is optional - if omitted, the server takes it from the Content-Disposition HEAD response or from the last URL segment. The response is the updated task / note / notification with source: "link" on the new items.

Detaching

detach_file_from_task / detach_file_from_info / detach_file_from_notification - work the same way for both upload and link (distinguished by source in JSONB). For an upload-style file that you uploaded, the quota is freed; for a link, nothing is physically removed - it just stops being attached.

Notifications (kind=2)

On top of tasks and notes, the assistant can create notifications - records that arrive on the user's device as a visible push banner (like a messenger message). Handy for reminding about something immediately, not "by tomorrow morning".

• create_notification - title, message?, priority? (0..3, severity for icon/color), list_id? (if omitted - "Inbox"). You can pass file_ids and links right at creation.
• list_notifications / get_notification - read.
• update_notification / delete_notification - edit the text and soft-delete. The "read / unread" state is not managed through MCP - it's a client-side CRDT flag, set only by the user in the app.

The notification appears in the "Notifications" tab of the app and is placed in the specified list. On iPhone/iPad/Mac/Android it arrives as a push banner; the user can convert it to a task with a single tap.

Managing connections

Authorization follows the OAuth 2.1 standard. Active connections are visible and can be revoked at any time under Settings → MCP.