# Vortask

Vortask is a project and task management platform with a REST API, webhooks, and an MCP (Model Context Protocol) server for AI agent access.

## MCP Server (Recommended for AI agents)

The fastest way for an AI agent to access Vortask is via the hosted MCP server.

- **MCP server URL:** https://mcp.vortask.app
- **Transport:** Streamable HTTP (JSON-RPC over HTTP + SSE)
- **Auth:** Bearer token — pass a `vt_` API token in the `Authorization` header
- **Protocol version:** 2024-11-05

### Setup in Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "vortask": {
      "command": "npx",
      "args": ["-y", "vortask-mcp"],
      "env": {
        "VORTASK_API_URL": "https://api.vortask.app/api",
        "VORTASK_TOKEN": "vt_your_token_here"
      }
    }
  }
}
```

### Setup in Claude.ai (remote MCP)

1. Go to Settings → Integrations → Add MCP Server
2. URL: `https://mcp.vortask.app`
3. When prompted, paste your `vt_` API token

### Available MCP Tools (14 total)

- `get_context` — Full workspace snapshot: profile, all projects, recent tasks. **Call this first.**
- `list_projects` — List projects and your role in each
- `list_tasks` — List tasks with filters (status, priority, assignee, label, due date)
- `get_task` — Full task details including assignees and tags
- `get_task_history` — Audit trail of changes to a task
- `create_task` — Create a new task
- `bulk_create_tasks` — Create up to 100 tasks at once
- `update_task` — Update task fields (partial patch — only send changed fields)
- `delete_task` — Delete a task (Admin role required)
- `list_members` — Project members and pending invitations
- `create_project` — Create a new project
- `list_comments` — List comments on a task
- `add_comment` — Add a comment to a task
- `delete_comment` — Delete a comment

### Recommended agent workflow

1. Call `get_context` to understand the user's workspace
2. Use `list_tasks` with `status=Active` or `status=New` to find work items
3. Use `update_task` to change status, assignees, priority, or due dates
4. Use `add_comment` to leave notes on tasks

## REST API

Base URL: `https://api.vortask.app/api`

Authentication: `Authorization: Bearer vt_your_token`

All tokens are created at https://vortask.app → Profile → API Tokens.

Key endpoints:
- `GET /agent/context` — same composite snapshot as the `get_context` MCP tool
- `GET /projects` — list projects
- `GET /projects/{id}/tasks` — list tasks (supports ?status=, ?priority=, ?assigneeId=, ?label=, ?dueBefore=, ?dueAfter=)
- `GET /projects/{id}/tasks/{taskId}` — get task
- `POST /projects/{id}/tasks` — create task
- `POST /projects/{id}/tasks/{taskId}/update` — update task
- `POST /projects/{id}/tasks/{taskId}/delete` — delete task

Full API reference: https://vortask.app/docs
Swagger UI: https://api.vortask.app/swagger

## Token Scopes

Tokens can be scoped to limit access:
- `tasks:read` — read tasks and history
- `tasks:write` — create and update tasks
- `tasks:delete` — delete tasks
- `projects:read` — read projects and members
- `projects:write` — manage projects and members

A token with no scopes has full access (limited by the user's project role).