Developer Reference

REST API · MCP

Authentication

All API requests are authenticated with a personal API key sent as a Bearer token. Create one in Settings → API Keys.

Authorization: Bearer kr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

REST Endpoints

Projects

List all projects you can access

Create a new project

Get a single project with categories and members

Rename, share, or change project metadata

Permanently delete a project (owner only)

Create a category

Tasks

Create a task

Get a single task with notes and closing requisites

Update title, priority, status, deadline, etc.

Permanently delete a task

Close a task

Add a note

Get the full change history for a task

Generate or revoke a public sharing link

Get tags for a task

Add or remove tags from a task

Export tasks as JSON or CSV

Activity recap

Bulk-import tasks from JSON or CSV

Search tasks by title, description, tags or JIRA key. Every word is matched separately and results are ranked; closed tasks rank lower.

Apply the same change to up to 5000 tasks in one request and one transaction

Analytics and reporting data

Get your productivity score and stats

Chat / AI

Run a slash command or AI message

Get chat history for a project

Teams

List your teams

Create a new team

Update team name or settings

Delete a team (owner only)

Invite a member by email (role: manager, participant, commenter or viewer)

Account

Export all your data (GDPR)

Permanently delete your account

Create a new API key

Revoke an API key

Update user settings

List your notifications

MCP Server (Claude Code, Cursor, etc.)

The Karea MCP server lets any MCP-compatible client manage your tasks directly.

1. Install

Claude Code

claude mcp add karea -e KAREA_URL=https://karea.app -e KAREA_API_KEY=kr_... -- npx -y karea-mcp

Claude Desktop / Cursor / other tools

Add to your client's MCP config file:

{
  "mcpServers": {
    "karea": {
      "command": "npx",
      "args": ["-y", "karea-mcp"],
      "env": {
        "KAREA_URL": "https://karea.app",
        "KAREA_API_KEY": "kr_..."
      }
    }
  }
}

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · Cursor: .cursor/mcp.json · VS Code: use root key "servers" instead of "mcpServers"

2. Use it

Just talk naturally: "create a P1 task to fix the navbar bug"

Available tools

The server advertises 9 tools: one for reading, one per kind of change, one for deleting, the assistant and help, covering 69 actions. Each tool takes an action and a params object:

karea_tasks_write { action: "karea_create_task", params: { name: "Fix the navbar", priority: 1 } }
karea_read { action: "karea_list_tasks", params: { status: "in_progress" } }

Fewer, broader tools keep an agent's tool-selection step reliable. Set KAREA_MCP_LEGACY_TOOLS=1 in your MCP config to register all 69 actions as individual tools instead.

Read anything in Karea without changing it: projects, tasks, subtasks, notes, sticky notes, task documents and AI context, open questions, resources, meetings, reminders, Jira links, AI sessions, and the activity recap. The main entry point - start here.

Create and change tasks: create, edit one or many, close one or many, log finished or in-progress work, plus subtasks and closing requisites (the checklist a task needs before it can close).

Write notes: add or edit task notes (human-readable updates) and sticky notes, and write a task's markdown document or an entry of its AI Context (private cross-session memory). Overwrites what an edit replaces.

Create a project or a category inside one, or share a project with someone by email.

Create and edit meetings and put tasks or questions on their agenda; create, answer and edit open questions; create, snooze, dismiss or complete reminders.

Create, upload and update resources in the file/document library and attach them to tasks; link a task to a Jira issue or to an AI coding session.

Send a natural-language request to the Karea AI assistant, which may read or change your tasks to carry it out.

Delete or detach things. Permanent deletes (project, category, task, requisite, note, sticky note, question, resource, meeting) need confirm=true where stated; detaching a resource, task, question, Jira issue or AI session from what it is linked to.

Full JSON Schema and description for any action, so an agent can call it correctly. Omit the action to list every action grouped by tool.

MCP Troubleshooting

Common issues after installing or updating the MCP server.

New tools missing after an update

npx caches packages locally. After a new version is published, your client may still run the old one. Fix:

Clear the npx cache: npm cache clean --force
Remove stale npx copies: find ~/.npm/_npx -type d -name "node_modules" -exec sh -c 'if [ -d "$1/karea-mcp" ]; then rm -rf "$(dirname $1)"; fi' _ {} \;
Or ask for the newest version explicitly: change "karea-mcp" to "karea-mcp@latest" in your config
Reconnect your MCP client (e.g. /mcp in Claude Code, or restart your IDE)

Tools show in server but not in client

MCP clients enumerate tools once at connection time. If you updated the server mid-session, the client still has the old tool list. Reconnecting the MCP (/mcp) or restarting the session fixes this. If reconnecting alone doesn't work, clear the npx cache first (see above).

Claude Code skill (optional)

A companion to the MCP. The skill teaches Claude Code your Karea conventions so it picks the right tool automatically - e.g. when you ask "what's on my plate", "log that I fixed the bug yesterday", or "dump the debugging notes to HA42's doc".

Download skill (tar.gz)View SKILL.md

Install

mkdir -p ~/.claude/skills/karea
tar -xzf karea-claude-skill.tar.gz -C ~/.claude/skills/karea
# Restart Claude Code. Ask something like "what's on my plate today?" -
# the skill activates automatically.