Getting Started

Set up ULPI Tasks and start coordinating AI agents in 3 minutes

Your AI Agents Will Be Coordinating in 3 Minutes

No complex setup. No configuration files. Just 3 simple steps.

Time estimate: 3-5 minutes

Prerequisites:

• ULPI account (sign up free)
• At least one project created
• AI assistant with MCP support (Claude Desktop, Cursor, Windsurf, etc.)

---

Step 1: Enable Tasks Product

1. Navigate to Project Settings

   Dashboard → Select your project → Settings → Products

   Pro tip: Enable Tasks for your most active project first

2. Activate Tasks

   Click Enable next to “Tasks”

   Choose your plan:

   • Starter (Free): 100 tasks, 3 agents, text search
   • Pro ($29/mo): 1,000 tasks, 10 agents, semantic search, dependencies
   • Enterprise (Custom): Unlimited everything

   Instant activation: Tasks product is ready to use immediately

⏱️ Time: 30 seconds

---

Step 2: Configure Your AI Assistant

Claude Desktop

Add ULPI Tasks MCP server:

1. Open Claude Desktop settings
2. Navigate to Developer → MCP Servers
3. Click Add Server
4. Use these settings:

{
  "ulpi-tasks": {
    "command": "npx",
    "args": [
      "@ulpi/mcp-client",
      "tasks"
    ],
    "env": {
      "ULPI_API_KEY": "your-api-key-here",
      "ULPI_PROJECT_ID": "your-project-id"
    }
  }
}

5. Get your API key:

   • Dashboard → Settings → API Keys → Create Key

6. Get your Project ID:

   • Dashboard → Select project → URL shows /projects/123 (123 is your project ID)

7. Restart Claude Desktop

Verify: Start a new chat. Claude should say “Connected to ULPI Tasks” or show tasks tools available.

Cursor

Add ULPI Tasks to Cursor:

1. Open Cursor settings (Cmd+, or Ctrl+,)
2. Go to Features → MCP
3. Add new MCP server:

{
  "name": "ULPI Tasks",
  "command": "npx",
  "args": [
    "@ulpi/mcp-client",
    "tasks"
  ],
  "env": {
    "ULPI_API_KEY": "your-api-key-here",
    "ULPI_PROJECT_ID": "your-project-id"
  }
}

4. Reload Cursor (Cmd+Shift+P → “Reload Window”)

Get credentials: Dashboard → Settings → API Keys (create new key + copy project ID from URL)

Windsurf

Connect Windsurf to ULPI Tasks:

1. Open Windsurf settings
2. Navigate to Extensions → MCP Configuration
3. Add ULPI Tasks:

{
  "mcpServers": {
    "ulpi-tasks": {
      "command": "npx",
      "args": ["@ulpi/mcp-client", "tasks"],
      "env": {
        "ULPI_API_KEY": "your-api-key-here",
        "ULPI_PROJECT_ID": "your-project-id"
      }
    }
  }
}

4. Restart Windsurf

Other AI Tools (40+)

ULPI Tasks works with any MCP-compatible AI assistant:

• Claude Code
• Continue
• VSCode Copilot
• Cline
• Aider
• And 35+ more…

Generic setup:

1. Find MCP configuration in your AI tool’s settings
2. Add ULPI Tasks MCP server with command:
   npx @ulpi/mcp-client tasks
   
3. Set environment variables:
   • ULPI_API_KEY (from Dashboard → Settings → API Keys)
   • ULPI_PROJECT_ID (from project URL)

Need help? Check our assistant compatibility guide or email [e-mail]

⏱️ Time: 2 minutes

---

Step 3: Register Your First Agent & Create a Task

Automatic (Recommended)

Just ask your AI assistant to create a task:

You: "Create a task to refactor the authentication controller"

What happens automatically:

1. Agent registers itself (if first time):

   Agent: claude-desktop-main
   Status: Active
   Capabilities: ["code-generation", "refactoring"]
   

2. Task is created:

   Task Key: BACKEND-001
   Title: Refactor authentication controller
   Status: todo
   Assigned to: claude-desktop-main
   Created: 2025-01-12 14:23:00
   

Zero configuration: The agent auto-registers on first task creation. You don’t need to do anything!

Manual (Advanced)

Explicitly register the agent first:

You: "Register yourself as an agent named 'claude-main' with capabilities: code-generation, refactoring, testing"

Then create tasks:

You: "Create a task to add OAuth2 support"
You: "Create a bug task for session timeout issues"
You: "Create a feature task to implement user roles"

When to use manual registration:

• You want to customize agent name
• You want to pre-define capabilities
• You’re setting up multiple agents at once

⏱️ Time: 30 seconds

---

✅ You’re Done! What’s Next?

Create Your First Task

Ask your AI: “Create a task to refactor the auth system”

See it in action:

• Auto-generated task key (PROJECT-001)
• Assigned to your agent
• Ready to track status

View Tasks in Dashboard

Dashboard → Your Project → Tasks

See all tasks, filter by status, search by keyword

Update Task Status

Ask your AI: “Mark BACKEND-001 as in progress”

Track progress through the workflow

Search Tasks

Ask your AI: “What tasks are assigned to me?”

Or: “Show me all high priority bugs”

---

Common Workflows

🎯 Solo Developer with 1 AI Assistant

Use case: You + Claude Desktop working on a personal project

Workflow:

1. Create tasks as you think of them:

   "Create a task to add dark mode support"
   "Create a bug task for mobile layout issues"
   "Create a task to improve API response times"
   

2. Let your AI track progress:

   You: "What should we work on next?"
   Claude: "You have 3 todo tasks. Highest priority:
            FRONTEND-012 (dark mode support)"
   
   You: "Let's start on FRONTEND-012"
   Claude: *marks task as in_progress*
   

3. Mark completed when done:

   You: "Dark mode is done, mark it complete"
   Claude: *marks FRONTEND-012 as completed*
   

Result: Always know what needs to be done. Never lose track of work.

👥 Team with Multiple AI Assistants

Use case: Team of 3 developers, each using their own AI assistant

Workflow:

1. Each AI registers separately:

   Developer 1 + Claude Desktop → Agent: claude-main
   Developer 2 + Cursor → Agent: cursor-main
   Developer 3 + Windsurf → Agent: windsurf-main
   

2. Assign tasks to specific agents:

   Claude: "Create a task to refactor auth, assign to cursor-main"
   
   # Cursor gets notified (Pro+ only)
   Cursor: "You have a new task: BACKEND-042 (refactor auth)"
   

3. Track who’s working on what:

   You: "What is cursor-main working on?"
   Claude: "cursor-main has 2 tasks in progress:
            - BACKEND-042: Refactor auth
            - BACKEND-045: Add rate limiting"
   

4. Use dependencies to prevent conflicts:

   Claude: "Create a task to deploy auth changes,
            depends on BACKEND-042"
   
   # Can't complete deployment until BACKEND-042 is done
   

Pro feature: Task dependencies and notifications require Pro or Enterprise plan.

🔄 Complex Feature with Dependencies

Use case: Building OAuth2 support (requires multiple tasks in sequence)

Workflow:

1. Create parent task (epic):

   "Create an epic task for OAuth2 implementation"
   → BACKEND-050 (epic)
   

2. Create sub-tasks with dependencies:

   "Create a task to add OAuth2 database schema"
   → BACKEND-051
   
   "Create a task to implement OAuth2 endpoints,
    blocked by BACKEND-051"
   → BACKEND-052 (depends on BACKEND-051)
   
   "Create a task to add OAuth2 frontend UI,
    blocked by BACKEND-052"
   → BACKEND-053 (depends on BACKEND-052)
   
   "Create a task to test OAuth2 flow,
    blocked by BACKEND-053"
   → BACKEND-054 (depends on BACKEND-053)
   

3. Work through tasks in order:

   # Complete BACKEND-051 first
   You: "Mark BACKEND-051 as completed"
   
   # Now BACKEND-052 can start
   You: "Start BACKEND-052"
   Claude: *marks as in_progress*
   

4. Track overall progress:

   You: "What's the status of OAuth2 implementation?"
   Claude: "Epic BACKEND-050 progress:
            - BACKEND-051: ✅ Completed
            - BACKEND-052: 🔄 In Progress
            - BACKEND-053: ⏳ Blocked
            - BACKEND-054: ⏳ Blocked"
   

Result: Complex features stay organized. Dependencies prevent premature work.

🔍 Find Work Using Semantic Search

Use case: Quickly find relevant tasks without remembering exact titles

Examples:

You: "What authentication bugs are blocking deployment?"
Claude: "Found 2 tasks:
         - BACKEND-038: OAuth token refresh fails
         - BACKEND-041: Session cookies not secure"

You: "What high priority work is due this week?"
Claude: "3 tasks due by Friday:
         - FRONTEND-067: Finish mobile redesign (Critical)
         - BACKEND-072: Fix database migration (High)
         - BACKEND-080: Add error logging (Medium)"

You: "Show me all tasks related to performance"
Claude: "Found 5 tasks:
         - BACKEND-023: Optimize database queries
         - FRONTEND-034: Reduce bundle size
         - BACKEND-056: Add caching layer
         - ..."

Pro feature: Semantic search requires Pro or Enterprise plan. Starter plan has keyword search only.

---

Troubleshooting

❌ Agent Registration Failed

Error: “Failed to register agent: quota exceeded”

Cause: You’ve reached your agent limit for your plan:

• Starter: 3 agents
• Pro: 10 agents
• Enterprise: Unlimited

Fix:

1. Check how many agents you have:
   "List all registered agents"
   
2. Option 1: Delete inactive agents
3. Option 2: Upgrade to Pro or Enterprise

---

Error: “Agent name already exists”

Cause: An agent with that name is already registered

Fix:

1. Use a different name: claude-desktop-2
2. Or check if the agent exists:
   "Get agent information for claude-desktop"
   

❌ Task Creation Failed

Error: “Failed to create task: quota exceeded”

Cause: You’ve reached your task limit:

• Starter: 100 tasks per project
• Pro: 1,000 tasks per project
• Enterprise: Unlimited

Fix:

1. Check your quota:
   "Show task statistics"
   
2. Option 1: Delete completed tasks (frees up quota)
3. Option 2: Upgrade to Pro or Enterprise

---

Error: “Creator agent not found”

Cause: Agent hasn’t been registered yet

Fix: Let the agent auto-register by creating a task normally:

"Create a task to add feature X"

(Agent registers automatically on first task creation)

❌ Can't Update Task Status

Error: “Invalid status transition from ‘todo’ to ‘completed’”

Cause: Status workflow prevents skipping states

Valid workflow:

todo → in_progress → completed

Invalid:

todo → completed (must go through in_progress)

Fix: Follow the correct sequence:

"Mark BACKEND-001 as in progress"
# ... do the work ...
"Mark BACKEND-001 as completed"

---

Error: “Cannot complete task. Blocked by: BACKEND-038”

Cause: Task has dependencies that aren’t completed yet

Fix: Complete the blocking task first:

1. "Mark BACKEND-038 as completed"
2. Now you can: "Mark BACKEND-042 as completed"

🔍 Search Returns No Results

Problem: Semantic search returns 0 results for obvious queries

Possible causes:

1. Semantic search not enabled (Starter plan)

• Starter plan has keyword search only
• Upgrade to Pro for semantic search

2. Tasks recently created (indexing delay)

• Wait 10-30 seconds for indexing
• Try again

3. Query too vague

• Use more specific terms
• Include task type, status, or priority

Better queries:

❌ "bugs"
✅ "authentication bugs blocking deployment"

❌ "features"
✅ "high priority features due this week"

🔌 MCP Connection Issues

Problem: AI assistant doesn’t recognize ULPI Tasks commands

Diagnosis:

1. Check MCP server status in your AI assistant
2. Verify API key is correct
3. Verify project ID is correct

Fix for Claude Desktop:

// Check ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "ulpi-tasks": {
      "command": "npx",
      "args": ["@ulpi/mcp-client", "tasks"],
      "env": {
        "ULPI_API_KEY": "sk_...",  // Must start with sk_
        "ULPI_PROJECT_ID": "123"   // Numeric project ID
      }
    }
  }
}

Verify connection:

1. Restart your AI assistant
2. Start new chat
3. Check for “Connected to ULPI Tasks” message

Still stuck? Email [e-mail] with:

• Your AI assistant name
• Error message (if any)
• MCP configuration (remove API key before sending)

📊 Statistics Not Updating

Problem: Task statistics show old data

Possible causes:

1. Caching (normal)

• Statistics are cached for 5 minutes
• Wait 5 minutes for fresh data

2. Task status not saved

• Check task details: "Get task BACKEND-001"
• Verify status is what you expect

Force refresh:

"Show me updated task statistics"
# Or wait 5 minutes for cache to expire

---

Quick Reference

Essential Commands

# Create task
"Create a task to [description]"
"Create a bug task for [issue]"
"Create a feature task to [description]"

# Update status
"Mark [TASK-KEY] as in progress"
"Mark [TASK-KEY] as completed"
"Mark [TASK-KEY] as blocked"

# Search
"What tasks are assigned to me?"
"Show all high priority tasks"
"What bugs are blocking deployment?"

# Get details
"Get task [TASK-KEY]"
"What's the status of [TASK-KEY]?"

# Statistics
"Show task statistics"
"How many tasks do I have?"

Status Workflow

Valid Transitions:
==================
todo → in_progress
todo → cancelled

in_progress → blocked
in_progress → in_review
in_progress → completed
in_progress → cancelled

blocked → in_progress
blocked → cancelled

in_review → in_progress
in_review → completed
in_review → cancelled

completed → (terminal state)
cancelled → (terminal state)

Task Properties

Task Key: PROJECT-001 (auto-generated)

Required:
  - title: string (max 500 chars)
  - status: todo|in_progress|blocked|in_review|completed|cancelled

Optional:
  - description: string
  - priority: critical|high|medium|low (default: medium)
  - type: feature|bug|improvement|question|task|epic (default: task)
  - estimate_hours: integer
  - due_date: ISO 8601 date
  - tags: array of strings
  - assigned_to: agent name

Auto-set:
  - created_by: agent who created task
  - assigned_to: defaults to creator
  - started_at: when status → in_progress
  - completed_at: when status → completed

Subscription Limits

Starter (Free):
===============
- 100 tasks per project
- 3 agents per project
- 10 dependencies per task
- Text keyword search
- No bulk operations
- No notifications

Pro ($29/month):
================
- 1,000 tasks per project
- 10 agents per project
- 50 dependencies per task
- Semantic vector search
- Bulk operations (100 tasks at once)
- Notifications

Enterprise (Custom):
====================
- Unlimited tasks
- Unlimited agents
- Unlimited dependencies
- Everything in Pro +
  - Task templates
  - Advanced analytics
  - Custom workflows
  - SSO/SAML
  - SLA guarantee

---

What’s Next?

1. Learn Task Orchestration

   Explore workflows, dependencies, and coordination patterns

2. Try Bulk Operations

   Learn how to manage 100+ tasks efficiently

3. Explore All Tools

   Check the complete API reference for 18 MCP tools

---

Need Help?

Documentation

Advanced guides

Support

Email us anytime

Community

Join our Discord