REST API & MCP Server Docs — Claude Code Integration

− Claude Code Integration

TaskLeef includes a Model Context Protocol (MCP) server that allows AI assistants like Claude Code to manage your todos, boards, and Kanban workflows directly from the command line.

Quick Start

Get your API key from Settings → API Keys

Add the MCP server to Claude Code:

claude mcp add --transport http taskleef https://taskleef.com/mcp/messages -H "X-API-Key: YOUR_API_KEY"

Restart Claude Code
Verify it's working:
```
claude mcp list
```
You should see taskleef with a green checkmark.

Alternative: Manual Configuration

Add directly to ~/.claude.json:

{
  "mcpServers": {
    "taskleef": {
      "type": "http",
      "url": "https://taskleef.com/mcp/messages",
      "headers": {
        "X-API-Key": "your-api-key-here"
      }
    }
  }
}

Available Tools

The MCP server provides 40 tools across 7 domains:

Todos7 tools

Boards5 tools

Columns6 tools

Cards5 tools

Members5 tools

Tags7 tools

Comments5 tools

Example Usage

Once configured, you can ask Claude to manage your tasks naturally:

"Show me my todos for this week"
"Create a todo to review the quarterly report by Friday [work]"
"Move the authentication task to In Progress on the Sprint board"
"Add a comment to the API refactor task saying I've started the review"
"Tag all my meeting todos with the 'meetings' tag"
"Create a new board called 'Q2 Planning'"

Claude Desktop

For Claude Desktop, add to your MCP settings file:

{
  "mcpServers": {
    "taskleef": {
      "transport": {
        "type": "sse",
        "url": "https://taskleef.com/mcp/sse",
        "headers": {
          "X-API-Key": "your-api-key-here"
        }
      }
    }
  }
}

− Claude.ai & Claude CoWork

You can also use TaskLeef as a custom connector in Claude.ai (web), Claude Desktop, and Claude CoWork. The connector uses standard OAuth 2.1, so each user signs in with their own TaskLeef account — no shared API keys.

Setup

In Claude, open Settings → Connectors → Add custom connector (Claude.ai web) or Settings → Connectors (Claude Desktop / CoWork).
Enter the server URL:
```
https://taskleef.com/mcp/messages
```
Leave the optional OAuth Client ID and Client Secret fields blank — TaskLeef supports Dynamic Client Registration (RFC 7591), so Claude provisions a client automatically.
Click Add. Claude opens a browser tab to taskleef.com and asks you to sign in.
Sign in (email/password or SSO via GitHub, Google, Microsoft, or Apple), click Authorize, and you're done. Claude redirects back automatically.

What Claude can do

Once connected, Claude has access to all 40 MCP tools across todos, boards, columns, cards, members, tags, and comments. Try asking:

"What's on my plate this week?"
"Create a board called 'Q3 launch' and add columns for Backlog, Doing, and Done."
"Move the API refactor task to In Progress on my Sprint board."
"Tag every todo with 'meeting' in the title with the meetings tag."
"Summarize the open todos in my Inbox and suggest priorities for tomorrow."
"Add a comment to the deploy ticket saying I'm picking it up after lunch."

Tool safety annotations

Every tool the connector exposes is annotated for Claude so it can warn you before destructive actions:

Read-only13 tools

Mutating20 tools

Destructive7 tools

Destructive tools (delete todo, delete board, delete column, delete card, remove member, delete tag, delete comment) are flagged with destructiveHint: true, so Claude will ask for confirmation before running them.

Claude Code vs. Claude.ai / CoWork

Feature	Claude Code (CLI)	Claude.ai / CoWork
Setup	API key in CLI	OAuth in browser
Auth	Static `X-API-Key` header	Per-user OAuth 2.1 access token
Where it runs	Local terminal	Claude.ai / CoWork cloud
Token lifecycle	Manual rotation in Settings	Auto-refresh, revocable in Settings
Multi-user	One key per machine	Each user signs in separately

Revoking access

To disconnect a Claude session from TaskLeef, remove the connector inside Claude. Refresh tokens are also rotated on every use, so a stale token from a closed session can't be replayed.

Privacy

The OAuth flow happens entirely between your browser, taskleef.com, and Claude. Your password is never sent to Claude. The access token Claude receives is scoped to MCP only and bound to the audience https://taskleef.com/mcp — it can't be replayed against any other API.

− Authentication

The API supports two authentication methods:

1. API Key Authentication (Recommended)

Generate an API key from your Settings page and include it in the X-API-Key header:

curl -H "X-API-Key: your-api-key" \
  https://taskleef.com/api/todos

2. JWT Bearer Token

For browser-based applications, authenticate via the login endpoint:

curl -X POST https://taskleef.com/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "your-username", "password": "your-password"}'

Then include the token in subsequent requests:

curl -H "Authorization: Bearer your-jwt-token" \
  https://taskleef.com/api/todos

− Todos

GET/api/todos

Get all todos for the authenticated user.

curl -H "X-API-Key: your-api-key" \
  https://taskleef.com/api/todos

GET/api/todos/{id}

Get a specific todo by ID.

GET/api/inbox

Get todos that are not assigned to any project.

POST/api/todos

Create a new todo.

curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"title": "Buy groceries", "description": "Milk, eggs, bread"}' \
  https://taskleef.com/api/todos

Request Body

Field	Type	Required	Description
title	string	Yes	Todo title
description	string	No	Detailed description
dueDate	ISO 8601	No	Due date/time
priority	string	No	Low, Medium, High, or Urgent
projectId	UUID	No	Assign to a project

PUT/api/todos/{id}

Update an existing todo.

PATCH/api/todos/{id}/complete

Toggle todo completion status.

curl -X PATCH -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"isCompleted": true}' \
  https://taskleef.com/api/todos/{id}/complete

DELETE/api/todos/{id}

Delete a todo.

POST/api/todos/{parentId}/subtasks

Create a subtask under a parent todo.

curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"title": "Subtask title"}' \
  https://taskleef.com/api/todos/{parentId}/subtasks

− Projects

GET/api/projects

List all projects for the authenticated user.

POST/api/projects

Create a new project.

curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"title": "Work Tasks", "description": "Tasks for work"}' \
  https://taskleef.com/api/projects

GET/api/projects/{id}

Get a specific project with its todos.

PUT/api/projects/{id}

Update a project.

DELETE/api/projects/{id}

Delete a project (todos are moved to inbox).

− Kanban Boards

GET/api/boards

List all boards the user has access to.

POST/api/boards

Create a new board.

curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"title": "Sprint Board", "projectId": "project-uuid"}' \
  https://taskleef.com/api/boards

GET/api/boards/{id}

Get a specific board.

GET/api/boards/{boardId}/columns

Get all columns for a board.

GET/api/boards/{boardId}/todos

Get all todos that have cards on this board.

− Columns

POST/api/boards/{boardId}/columns

Create a new column on a board.

curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"title": "In Progress", "wipLimit": 3}' \
  https://taskleef.com/api/boards/{boardId}/columns

PUT/api/columns/{id}

Update a column (title, WIP limit, done criteria).

GET/api/columns/{columnId}/cards

Get all cards in a column.

DELETE/api/columns/{id}

Delete a column.

− Cards

Cards represent todos on a kanban board. A todo can have cards on multiple boards.

POST/api/columns/{columnId}/cards

Create a card for a todo in a column.

curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"todoId": "todo-uuid"}' \
  https://taskleef.com/api/columns/{columnId}/cards

PUT/api/cards/{id}

Update a card (move to different column or subColumn).

# Move card to a different column
curl -X PUT -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"columnId": "new-column-uuid", "subColumn": "Inbox"}' \
  https://taskleef.com/api/cards/{id}

# Move card to Done subColumn
curl -X PUT -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"subColumn": "Done"}' \
  https://taskleef.com/api/cards/{id}

SubColumn Values

Inbox - Active items in the column
Done - Completed items within the column
Blocked - Items waiting on external dependencies

DELETE/api/cards/{id}

Remove a card from the board (does not delete the todo).

− Tags

GET/api/tags

List all tags for the authenticated user.

POST/api/tags

Create a new tag.

curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "urgent"}' \
  https://taskleef.com/api/tags

PUT/api/tags/{id}

Update a tag.

DELETE/api/tags/{id}

Delete a tag.

− Comments

GET/api/todos/{todoId}/comments

Get all comments on a todo.

POST/api/todos/{todoId}/comments

Add a comment to a todo.

curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"text": "This is my comment"}' \
  https://taskleef.com/api/todos/{todoId}/comments

PUT/api/comments/{id}

Update a comment.

DELETE/api/comments/{id}

Delete a comment.

− Response Format

Success Responses

Successful requests return JSON with the requested data:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Buy groceries",
  "description": "Milk, eggs, bread",
  "isCompleted": false,
  "createdAt": "2024-01-15T10:30:00Z"
}

Error Responses

Errors return appropriate HTTP status codes:

400 - Bad Request (invalid input)
401 - Unauthorized (missing or invalid authentication)
403 - Forbidden (insufficient permissions)
404 - Not Found
500 - Internal Server Error