TaskLabs
Back to home

MCP & API keys

TaskLabs exposes a modern, sessionless MCP endpoint at POST /api/mcp. It combines Linear-style task and project operations with the same connected Google Calendar used by the app.

Modern stateless MCP

The endpoint implements MCP 2026-07-28. Every request is independently authenticated and carries its protocol metadata. There is no initialize handshake, MCP session ID, GET event stream, DELETE termination call, or transport resumption state.

The server is created fresh for every request with the official MCP TypeScript SDK. Responses are JSON unless a request-scoped operation needs an SSE response. Durable planner state and idempotency records live in Convex, not in an MCP transport session.

Create an API key

  • Open Settings → Profile → API keys.
  • Choose only the scopes the client needs.
  • Set an optional expiry date.
  • Copy the token immediately; the raw value is shown once.

Tool discovery is filtered by the key’s scopes. Rotate a key to mint a replacement and invalidate the old secret, or revoke it immediately.

Planning scopes

ScopeAccess
tasks:read / tasks:writeTask discovery, mutation, scheduling, and comments
projects:read / projects:writeProject discovery, mutation, and updates
events:read / events:writeConnected Google Calendar agenda, free time, and event CRUD
labels:readLabel dictionary returned by get_context
workspaces:readWorkspace metadata returned by get_context
members:readMember dictionary and identity resolution
search:readWorkspace task, project, and label search

The endpoint

text
POST /api/mcp
Authorization: Bearer <TaskLabs API key>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/list
  • Every request requires a bearer API key; query-string tokens are rejected.
  • Mcp-Name is also required for tool calls.
  • GET and DELETE return 405.
  • The Host and any browser Origin must match a configured allowed origin.
  • Tool failures use isError: true without stack traces.
  • The SDK rejects missing, unsupported, or header-mismatched protocol metadata.

Modern tools/list request

bash
curl -sS https://your.domain/api/mcp \
  -H 'Authorization: Bearer tlk_live_exampleprefix_exampleSecretValueDoNotUse' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list",
    "params":{"_meta":{
      "io.modelcontextprotocol/protocolVersion":"2026-07-28",
      "io.modelcontextprotocol/clientCapabilities":{}}}}}'

Use example tokens in docs only

Never paste generated local or production tokens into tracked files, logs, test snapshots, or handoff notes.

The 18-tool planning surface

  • Orientation — get_context, search
  • Tasks — list_tasks, get_task, save_task, delete_task
  • Projects — list_projects, get_project, save_project, delete_project
  • Collaboration — list_notes, add_note, delete_note
  • Calendar — list_agenda, suggest_time, get_event, save_event, delete_event

save_task, save_project, and save_event create when their ID is absent and patch when it is present. Task creation and event creation accept caller-generated request IDs for retry-safe external writes.

save_task can also schedule or unschedule its calendar block. Event and task time inputs distinguish timed RFC 3339 values from all-day dates, whose end date is exclusive. Recurring event updates and deletes require an explicit THIS, FOLLOWING, or SERIES scope.

What “my tasks” means

list_tasks defaults to tasks assigned to the API-key owner. Use assignment: any only for a shared workspace view. A visible task is never assumed to be the caller’s task merely because it appears in a shared calendar.

Every returned task includes its assignees plus derived assignedToCaller, createdByCaller, and assignmentState fields. An empty assignee list means unassigned. Creator and assignee are separate.

Structured outputs

Every tool declares an output schema and returns both a compact text block and structuredContent. Results include the caller and workspace IDs, normalized filters where applicable, and explicit provider/source fields for agenda rows.

Security notes

  • API keys never create browser sessions and are checked on every request.
  • Keys are hashed at rest, scope-limited, expirable, rotatable, revocable, and rate-limited.
  • CORS_ALLOWED_ORIGINS must contain exact origins; wildcard CORS is not used.
  • The workspace is bound to the key and is never accepted as a model-selected tool argument.
PreviousUsing TaskLabsNextProduction