MCP Tools Reference

Complete reference for TaskDriver's Model Context Protocol (MCP) tools.

Overview

TaskDriver provides 21 MCP tools for complete task management and orchestration. These tools enable LLM agents to create projects, manage tasks, coordinate with other agents, and monitor system health.

Getting Started

Starting the MCP Server

bun run mcp

The server runs on stdio transport and provides all tools immediately.

Important Usage Notes

Before starting any task, agents should:

Get project details using get_project to read project instructions
Review project-specific guidance and requirements
Understand the context and constraints

Project Management Tools

create_project

Create a new project for organizing tasks and agents.

Parameters:

name (required) - Project name (alphanumeric, hyphens, underscores only)
description (required) - Project description
instructions (optional) - Project instructions for agents - important guidance that should be read before starting any task
config (optional) - Project configuration
- defaultMaxRetries (0-10) - Default max retries for tasks
- defaultLeaseDurationMinutes (1-1440) - Default lease duration in minutes
- reaperIntervalMinutes (1-60) - Reaper interval for cleaning up expired tasks

Example:

{
  "name": "ai-code-analysis",
  "description": "AI-powered code analysis and review project",
  "instructions": "Before starting any task, review the project guidelines and coding standards. Focus on security, performance, and maintainability.",
  "config": {
    "defaultMaxRetries": 3,
    "defaultLeaseDurationMinutes": 15,
    "reaperIntervalMinutes": 5
  }
}

list_projects

List all projects with optional filtering.

Parameters:

status (optional) - Filter by status: active, closed, all (default: active)
limit (optional) - Maximum number of projects to return (1-100)
offset (optional) - Number of projects to skip (minimum: 0)

Example:

{
  "status": "active",
  "limit": 10
}

get_project

Get detailed information about a specific project. This includes project instructions that agents should read before starting any task.

Parameters:

projectId (required) - Project ID (UUID)

Example:

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000"
}

update_project

Update project properties.

Parameters:

projectId (required) - Project ID (UUID)
description (optional) - New project description
instructions (optional) - New project instructions for agents
status (optional) - Project status: active, closed
config (optional) - Project configuration updates

Example:

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "description": "Updated project description",
  "instructions": "Updated instructions for agents",
  "status": "active"
}

Task Type Management Tools

create_task_type

Create a new task type template for a project.

Parameters:

projectId (required) - Project ID (UUID)
name (required) - Task type name (alphanumeric, hyphens, underscores only)
template (optional) - Task instruction template with {{variable}} placeholders
variables (optional) - Array of variable names used in the template
duplicateHandling (optional) - How to handle duplicate tasks: ignore, fail, allow (default: allow)
maxRetries (optional) - Maximum retry attempts (0-10)
leaseDurationMinutes (optional) - Lease duration in minutes (1-1440)

Example:

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "code-security-analysis",
  "template": "Analyze the codebase at {{repository_url}} on branch {{branch_name}} for security vulnerabilities. Focus on {{security_aspects}} and provide a detailed report.",
  "variables": ["repository_url", "branch_name", "security_aspects"],
  "duplicateHandling": "ignore",
  "maxRetries": 3,
  "leaseDurationMinutes": 30
}

list_task_types

List all task types for a project.

Parameters:

projectId (required) - Project ID (UUID)

Example:

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000"
}

Task Management Tools

create_task

Create a new task for execution.

Parameters:

projectId (required) - Project ID (UUID)
typeId (required) - Task type ID (UUID)
instructions (required) - Task instructions (can contain template variables)
variables (optional) - Key-value pairs for template variable substitution
batchId (optional) - Batch ID for grouping related tasks

Example:

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "typeId": "660e8400-e29b-41d4-a716-446655440001",
  "instructions": "Analyze security vulnerabilities in the authentication system",
  "variables": {
    "repository_url": "https://github.com/company/webapp",
    "branch_name": "main",
    "security_aspects": "authentication,authorization,input-validation"
  },
  "batchId": "batch-security-audit-2024"
}

list_tasks

List tasks with optional filtering.

Parameters:

projectId (required) - Project ID (UUID)
status (optional) - Filter by task status: queued, running, completed, failed
assignedTo (optional) - Filter by assigned agent name
batchId (optional) - Filter by batch ID
typeId (optional) - Filter by task type ID
limit (optional) - Maximum number of tasks to return (1-1000, default: 100)
offset (optional) - Number of tasks to skip (minimum: 0)

Example:

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "limit": 50,
  "offset": 0
}

get_task

Get detailed information about a specific task.

Parameters:

projectId (required) - Project ID (UUID)
taskId (required) - Task ID (UUID)

Example:

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "taskId": "770e8400-e29b-41d4-a716-446655440002"
}

Agent Management Tools

Important: Agents are now ephemeral queue workers, not persistent entities. They don't need registration - agents just get tasks from the queue using their name. Agent names are only used for reconnection after disconnects.

get_next_task

Get the next available task from the project queue. If the agent name has an existing task lease, that task is resumed. Otherwise, a new task is assigned. Before starting any task, agents should first get project instructions using get_project.

Parameters:

projectId (required) - Project ID or name
agentName (optional) - Agent name (will be auto-generated if not provided)

Example:

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "agentName": "security-analysis-agent"
}

Returns:

On success: Task object with full instructions and lease information
On failure: Error indicating no tasks available (agents can handle this to stop processing)

peek_next_task

Check if tasks are available in the project queue without assigning them. Perfect for determining if agents should be launched.

Parameters:

projectId (required) - Project ID or name

Example:

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000"
}

Returns:

On success: Number of tasks available
On failure: No tasks available in queue

list_active_agents

List agents currently working on tasks (agents with active task leases). This is for monitoring purposes - agents are ephemeral and only appear here when actively working.

Parameters:

projectId (required) - Project ID or name

Example:

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000"
}

Task Execution Tools

complete_task

Mark a task as completed with results. This releases the task lease and makes the agent available for new work.

Parameters:

agentName (required) - Agent name
projectId (required) - Project ID or name
taskId (required) - Task ID
result (required) - Task execution result (string or JSON)
outputs (optional) - Structured task outputs

Example:

{
  "agentName": "security-analysis-agent",
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "taskId": "770e8400-e29b-41d4-a716-446655440002",
  "result": "Security analysis completed successfully. Found 3 critical vulnerabilities and 5 medium-risk issues.",
  "outputs": {
    "vulnerabilities_found": 8,
    "critical_count": 3,
    "high_count": 0,
    "medium_count": 5,
    "report_url": "https://reports.example.com/security-123"
  }
}

fail_task

Mark a task as failed with error information. This releases the task lease and either requeues the task for retry or marks it permanently failed.

Parameters:

agentName (required) - Agent name
projectId (required) - Project ID or name
taskId (required) - Task ID (UUID)
error (required) - Error message or description
canRetry (optional) - Whether the task can be retried (default: true)

Example:

{
  "agentName": "security-analysis-agent",
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "taskId": "770e8400-e29b-41d4-a716-446655440002",
  "error": "Repository access denied. Authentication failed.",
  "canRetry": true
}

Status and Monitoring Tools

get_project_stats

Get project statistics and status overview.

Parameters:

projectId (required) - Project ID (UUID)

Example:

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000"
}

health_check

Check the health status of the TaskDriver system.

Parameters: None

Example:

{}

Lease Management Tools

extend_task_lease

Extend the lease duration for a running task to give an agent more time.

Parameters:

taskId (required) - ID of the task to extend the lease for
extensionMinutes (required) - Number of minutes to extend the lease by (1-1440)

Example:

{
  "taskId": "770e8400-e29b-41d4-a716-446655440002",
  "extensionMinutes": 30
}

get_lease_stats

Get lease and task statistics for a project to monitor system health.

Parameters:

projectId (required) - ID of the project to get lease statistics for

Example:

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000"
}

cleanup_expired_leases

Manually trigger cleanup of expired task leases for a project.

Parameters:

projectId (required) - ID of the project to cleanup expired leases for

Example:

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000"
}

Common Workflows

Agent Task Execution Workflow

Get Project Instructions (Essential first step):

{
  "tool": "get_project",
  "parameters": {
    "projectId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Check for Available Tasks (Optional - for scripting):

{
  "tool": "peek_next_task",
  "parameters": {
    "projectId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Get Next Task (No agent registration needed):

{
  "tool": "get_next_task",
  "parameters": {
    "projectId": "550e8400-e29b-41d4-a716-446655440000",
    "agentName": "my-agent"
  }
}

Complete Task:

{
  "tool": "complete_task",
  "parameters": {
    "agentName": "my-agent",
    "projectId": "550e8400-e29b-41d4-a716-446655440000",
    "taskId": "task-id",
    "result": "Task completed successfully"
  }
}

Project Setup Workflow

Create Project:

{
  "tool": "create_project",
  "parameters": {
    "name": "my-project",
    "description": "Project description",
    "instructions": "Important instructions for agents"
  }
}

Create Task Types:

{
  "tool": "create_task_type",
  "parameters": {
    "projectId": "project-id",
    "name": "analysis-task",
    "template": "Analyze {{target}} for {{focus}}"
  }
}

Create Tasks:

{
  "tool": "create_task",
  "parameters": {
    "projectId": "project-id",
    "typeId": "task-type-id",
    "instructions": "Specific task instructions",
    "variables": {"target": "webapp", "focus": "security"}
  }
}

Monitoring Workflow

Check Project Status:

{
  "tool": "get_project_stats",
  "parameters": {
    "projectId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Monitor System Health:

{
  "tool": "health_check",
  "parameters": {}
}

Clean Up Expired Leases:

{
  "tool": "cleanup_expired_leases",
  "parameters": {
    "projectId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Best Practices

For Agents

Always read project instructions first using get_project
Use descriptive agent names for easy identification and reconnection
Handle task failures gracefully with meaningful error messages using fail_task
Extend leases for long-running tasks using extend_task_lease
Provide structured outputs in complete_task for better tracking

For Project Managers

Provide clear project instructions that agents should follow
Create specific task types with well-defined templates
Monitor project statistics regularly using get_project_stats
Clean up expired leases periodically
Use batch IDs to group related tasks for better organization

Error Handling

Check tool responses for error conditions
Retry failed operations with appropriate backoff
Use fail_task with meaningful error messages
Monitor lease expiration and extend when necessary

Integration Examples

With LangChain

from langchain.tools import Tool

def create_taskdriver_tools(mcp_client):
    return [
        Tool(
            name="get_project",
            description="Get project details and instructions",
            func=lambda project_id: mcp_client.call_tool("get_project", {"projectId": project_id})
        ),
        Tool(
            name="get_next_task",
            description="Get next task assignment",
            func=lambda project_id, agent_name: mcp_client.call_tool("get_next_task", {
                "projectId": project_id,
                "agentName": agent_name
            })
        ),
        # ... more tools
    ]

With AutoGen

from autogen import ConversableAgent

def create_taskdriver_agent(mcp_client):
    return ConversableAgent(
        name="taskdriver_agent",
        system_message="You are a task management agent. Always get project instructions before starting work.",
        tools=[
            {
                "name": "get_project",
                "description": "Get project details and instructions",
                "parameters": {"projectId": {"type": "string"}},
                "function": lambda project_id: mcp_client.call_tool("get_project", {"projectId": project_id})
            },
            {
                "name": "get_next_task",
                "description": "Get next task assignment",
                "parameters": {"projectId": {"type": "string"}, "agentName": {"type": "string"}},
                "function": lambda project_id, agent_name: mcp_client.call_tool("get_next_task", {
                    "projectId": project_id,
                    "agentName": agent_name
                })
            }
        ]
    )

Troubleshooting

Common Issues

"Project not found" - Verify project ID is correct
"No tasks available" - Check if tasks exist and are queued
"Lease expired" - Task took too long, extend lease or handle failure
"Validation error" - Check parameter types and constraints
"Agent name mismatch" - Ensure agent name matches between get_next_task and complete_task/fail_task

Debug Steps

Use health_check to verify system status
Check get_project_stats for project health
List tasks to verify they exist and are in expected state
Use list_active_agents to see which agents are currently working
Monitor lease statistics with get_lease_stats
Clean up expired leases if needed

For more detailed troubleshooting, see the Configuration Guide and Architecture Overview.

FilesExpand file tree

mcp-tools.md

Latest commit

History

mcp-tools.md

File metadata and controls

MCP Tools Reference

Overview

Getting Started

Starting the MCP Server

Important Usage Notes

Project Management Tools

create_project

list_projects

get_project

update_project

Task Type Management Tools

create_task_type

list_task_types

Task Management Tools

create_task

list_tasks

get_task

Agent Management Tools

get_next_task

peek_next_task

list_active_agents

Task Execution Tools

complete_task

fail_task

Status and Monitoring Tools

get_project_stats

health_check

Lease Management Tools

extend_task_lease

get_lease_stats

cleanup_expired_leases

Common Workflows

Agent Task Execution Workflow

Project Setup Workflow

Monitoring Workflow

Best Practices

For Agents

For Project Managers

Error Handling

Integration Examples

With LangChain

With AutoGen

Troubleshooting

Common Issues

Debug Steps