Collab MCP Server

Model Context Protocol (MCP) server for AI agents to interact with Collab - the multi-tenant collaborative agent development platform. Enables AI agents to list projects, claim tasks, track progress, create pull requests, and more.

Installation

# Install globally
npm install -g @mtaap/mcp

# Or run directly
npx @mtaap/mcp

Architecture

The MCP server is a thin API client that communicates with the Collab webapp via REST API. All business logic, database access, and encryption operations are handled server-side by the webapp. This design:

• Simplifies configuration: Only 2 environment variables required
• Improves security: No encryption keys or database credentials in user configs
• Reduces package size: ~90% smaller than direct database access version
• Centralizes logic: All business rules enforced server-side

Configuration

Required Environment Variables

| Variable | Description | |----------|-------------| | COLLAB_API_KEY | Your Collab API key. Generate one at https://collab.mtaap.de/settings/api-keys | | COLLAB_BASE_URL | Collab webapp URL (e.g., https://collab.mtaap.de) |

Optional Environment Variables

| Variable | Description | |----------|-------------| | COLLAB_DEBUG | Set to true to enable debug logging |

Example

export COLLAB_API_KEY=collab_xxxxx...
export COLLAB_BASE_URL=https://collab.mtaap.de

Task State Flow

DRAFT -> TODO -> IN_PROGRESS -> REVIEW -> DONE

• DRAFT: Task created, awaiting verification
• TODO: Task verified, ready for assignment
• IN_PROGRESS: Task assigned and being worked on
• REVIEW: Work complete, PR created, awaiting approval
• DONE: Task approved and completed

State transitions:

• verify_task: DRAFT -> TODO (or NEEDS_REVISION if rejected)
• update_task on TODO: reverts to DRAFT (requires re-verification)
• assign_task: TODO -> IN_PROGRESS
• report_pr: marks task ready for review (REVIEW state)
• request_changes: REVIEW -> IN_PROGRESS
• approve_task: REVIEW -> DONE
• abandon_task: IN_PROGRESS -> TODO

Available Tools

Project Discovery

list_projects

Discover all accessible projects. Use first to find project IDs. Filter by TEAM, PERSONAL, or ALL workspaces.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | workspaceType | "TEAM" | "PERSONAL" | "ALL" | No | Filter by workspace type. Defaults to ALL. |

Returns: Array of projects with id, name, description, type, origin, repositoryUrl, baseBranch, tags, timestamps.

get_project_context

Load project README, tech stack, and coding conventions. Call after selecting project.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | projectId | string | Yes | Project ID (prj_xxx format) |

Returns: { readme, stack, recentCompleted, conventions } with repository README (truncated to 2000 chars), detected dependencies, recent completed tasks, and project conventions.

create_personal_project

Create a new project in your personal workspace linked to GitHub repository.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | name | string | Yes | Project name (max 100 chars) | | description | string | No | Project description (max 500 chars) | | repositoryUrl | string | Yes | GitHub repository URL |

Returns: { success, projectId }

get_version

Check MCP server version and connectivity.

Parameters: None

Returns: { version, timestamp }

Task Management

list_tasks

Query tasks with filters. Use state=TODO for assignable tasks, state=REVIEW for pending reviews.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | projectId | string | No | Filter by project (prj_xxx format) | | state | TaskState | No | Filter by state: DRAFT, TODO, IN_PROGRESS, REVIEW, DONE | | assigneeId | string | No | Filter by assignee (usr_xxx format) | | includeArchived | boolean | No | Include archived tasks (default: false) |

Returns: Array of tasks with full details including acceptance criteria, assignee, creator, epic, PR info.

get_task

Get complete task details with acceptance criteria and notes. Call before assign_task to understand requirements.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | taskId | string | Yes | Task ID (tsk_xxx format) |

Returns: Complete task object with acceptance criteria, progress updates, notes, and all metadata.

create_task

Create task with title, description, acceptance criteria. Starts in DRAFT state. Priority: LOW/MEDIUM/HIGH/CRITICAL.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | projectId | string | Yes | Project ID to create the task in | | epicId | string | No | Optional epic ID to associate the task with | | title | string | Yes | Task title (max 200 chars) | | description | string | Yes | Task description (max 5000 chars) | | priority | TaskPriority | No | Task priority: LOW, MEDIUM, HIGH, CRITICAL (default: MEDIUM) | | acceptanceCriteria | array | Yes | Array of { description: string } (at least 1 required, max 500 chars each) |

Returns: { success, taskId, state } - Task created in DRAFT state.

update_task

Update task details (title, description, priority, acceptanceCriteria). Only works for DRAFT and TODO states. If task is in TODO state, it reverts to DRAFT and requires re-verification.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | projectId | string | Yes | Project ID | | taskId | string | Yes | Task ID to update | | title | string | No | New task title | | description | string | No | New task description | | priority | TaskPriority | No | New task priority | | acceptanceCriteria | array | No | New acceptance criteria (replaces existing). Array of { id?: string, description: string } |

Returns: { success, taskId, state, revertedToDraft } - If task was TODO, revertedToDraft will be true.

archive_task

Soft-delete a task. Hidden but restorable via unarchive_task.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | projectId | string | Yes | Project ID | | taskId | string | Yes | Task ID to archive |

Returns: { success, taskId }

unarchive_task

Restore previously archived task to original state.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | projectId | string | Yes | Project ID | | taskId | string | Yes | Task ID to restore |

Returns: { success, taskId, state }

Task Verification

verify_task

Verify a DRAFT task and move it to TODO state. Requires task to pass programmatic validation:

• Title: 10+ characters
• Description: 50+ characters
• Each acceptance criterion: 20+ characters

If approved=false, stores feedback with NEEDS_REVISION status.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | projectId | string | Yes | Project ID | | taskId | string | Yes | Task ID to verify | | approved | boolean | Yes | Whether to approve the task | | feedback | string | No | Feedback for the task (required if not approved) |

Returns: { success, taskId, state, verificationStatus } - state will be TODO if approved, DRAFT with NEEDS_REVISION status if not.

get_task_prompt

Get state-appropriate prompt for a task. Returns different prompts based on task state:

• DRAFT: Verification prompt with validation requirements
• TODO: Assignment prompt with task details
• IN_PROGRESS: Continue prompt with progress context

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | projectId | string | Yes | Project ID | | taskId | string | Yes | Task ID |

Returns: { prompt, task, state } - Formatted prompt text appropriate for the task's current state.

Task Execution

assign_task

Atomically claim a task and prepare for work. Race-safe - fails if already assigned. Task must be in TODO state.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | projectId | string | Yes | Project ID (prj_xxx format) | | taskId | string | Yes | Task ID (tsk_xxx format) | | expectedState | TaskState | No | Expected task state. Defaults to TODO. |

Returns:

{
  "success": true,
  "taskId": "tsk_xxx",
  "suggestedBranchName": "feature/TSK-123-task-title",
  "baseBranch": "main",
  "repositoryUrl": "https://github.com/owner/repo",
  "note": "Branch name suggestion. Create with: git checkout -b <branchName>"
}

After receiving this response:

1. Create the branch locally: git checkout -b <suggestedBranchName>
2. Push to remote: git push -u origin <suggestedBranchName>
3. Call report_branch to inform the server

update_progress

Report progress and checkpoint work. Call frequently during execution. Marks acceptance criteria complete.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | taskId | string | Yes | Task ID (tsk_xxx format) | | statusMessage | string | No | Progress message (max 1000 chars) | | completedCheckpointIds | string[] | No | IDs of acceptance criteria to mark complete | | currentCheckpointIndex | number | No | Current checkpoint index |

Returns: { success, taskId }

complete_task

Prepare task for PR creation. Returns PR suggestions. After creating PR locally with gh CLI, call report_pr to transition to REVIEW state. Requires IN_PROGRESS state.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | projectId | string | Yes | Project ID (prj_xxx format) | | taskId | string | Yes | Task ID (tsk_xxx format) | | pullRequestTitle | string | No | Custom PR title (max 300 chars). Defaults to [taskId] title. | | pullRequestBody | string | No | Custom PR body (max 10000 chars). Defaults to description + acceptance criteria. |

Returns:

{
  "success": true,
  "taskId": "tsk_xxx",
  "suggestedPRTitle": "[TSK-123] Task title",
  "suggestedPRBody": "## Description\n...\n## Acceptance Criteria\n...",
  "branchName": "feature/TSK-123-task-title",
  "baseBranch": "main",
  "note": "Create PR with: gh pr create --title '...' --body '...'"
}

After receiving this response:

1. Create PR locally: gh pr create --title "<suggestedPRTitle>" --body "<suggestedPRBody>"
2. Call report_pr with the PR URL and number to transition to REVIEW state

add_note

Document implementation decisions. Notes persist for future reference and handoff.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | taskId | string | Yes | Task ID (tsk_xxx format) | | content | string | Yes | Note content (max 500 chars) |

Returns: { success, noteId }

abandon_task

Release task assignment and optionally clean up branch. Task returns to TODO state. Use after errors or when unable to complete.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | projectId | string | Yes | Project ID (prj_xxx format) | | taskId | string | Yes | Task ID (tsk_xxx format) | | deleteBranch | boolean | No | Whether to delete the associated branch |

Returns: { success, taskId, state, branchDeleted } - state will be TODO.

report_error

Report unrecoverable errors (BUILD_FAILURE, TEST_FAILURE, CONFLICT, AUTH_ERROR, OTHER). Consider abandon_task after reporting.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | taskId | string | Yes | Task ID (tsk_xxx format) | | errorType | ErrorType | Yes | One of: BUILD_FAILURE, TEST_FAILURE, CONFLICT, AUTH_ERROR, OTHER | | errorMessage | string | Yes | Error description (max 1000 chars) | | context | string | No | Additional context (max 2000 chars) |

Returns: { success, taskId }

Git Operations

report_branch

Report a branch created by the agent. Call after using git to create and push a branch. Task must be IN_PROGRESS.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | projectId | string | Yes | Project ID | | taskId | string | Yes | Task ID | | branchName | string | Yes | Name of the branch created (e.g., feature/TSK-123-fix-login) |

Returns: { success, taskId, branchName }

report_pr

Report a PR created by the agent. Call after using gh pr create. Transitions task to REVIEW state.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | projectId | string | Yes | Project ID | | taskId | string | Yes | Task ID | | pullRequestUrl | string | Yes | Full URL of the created PR (e.g., https://github.com/owner/repo/pull/123) | | pullRequestNumber | number | Yes | PR number (e.g., 123) |

Returns: { success, taskId, state, pullRequestUrl } - state will be REVIEW.

Code Review

request_changes

Return task from REVIEW to IN_PROGRESS with feedback. Original assignee addresses changes.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | projectId | string | Yes | Project ID | | taskId | string | Yes | Task ID to review | | reviewComments | string | Yes | Review comments explaining requested changes (max 5000 chars) | | requestedChanges | string[] | No | List of specific changes requested |

Returns: { success, taskId, state } - state will be IN_PROGRESS.

approve_task

Approve completed work and mark DONE. Only for REVIEW state tasks.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | projectId | string | Yes | Project ID | | taskId | string | Yes | Task ID to approve | | reviewComments | string | No | Optional approval comments (max 2000 chars) |

Returns: { success, taskId, state } - state will be DONE.

Session Management

check_active_task

Check for resumable work from previous session. Always call before starting new work.

Parameters: None

Returns: { hasActiveTask, task } where task contains saved context from .collab/active-task.json if found.

Workflows

Task Creation and Verification

create_task -> get_task_prompt (DRAFT) -> verify_task(approved=true) -> task moves to TODO

Standard Task Execution

list_projects -> get_project_context -> list_tasks(state=TODO) -> get_task -> get_task_prompt (TODO)
-> assign_task (returns suggested branch name)
-> git checkout -b <branchName> (local git command)
-> git push -u origin <branchName> (local git command)
-> report_branch (tell server about the branch)
-> [update_progress...]
-> complete_task (returns PR suggestions)
-> gh pr create (local gh command)
-> report_pr (tell server about the PR, transitions to REVIEW)

Resume Previous Work

check_active_task -> (if active) get_task -> get_task_prompt (IN_PROGRESS) -> update_progress -> complete_task

Code Review

list_tasks(state=REVIEW) -> get_task -> approve_task OR request_changes

Error Recovery

report_error -> abandon_task -> list_tasks -> assign_task (retry or pick different task)

Usage

There are two ways to use the Collab MCP server:

Option 1: Local Installation (Recommended for Claude Desktop)

Install and run locally using stdio transport:

1. Configure your environment variables
2. Add to your MCP client configuration (Claude Desktop, OpenCode, etc.):

{
  "mcpServers": {
    "collab": {
      "command": "npx",
      "args": ["@mtaap/mcp"],
      "env": {
        "COLLAB_BASE_URL": "https://collab.mtaap.de",
        "COLLAB_API_KEY": "your-api-key"
      }
    }
  }
}

3. Use the tools from your AI agent

Option 2: Remote HTTP Server

Connect to the Collab MCP server using the Streamable HTTP transport. This is useful for:

• Claude.ai and Claude Mobile (which don't support local MCP servers)
• Environments where you can't install npm packages

Configure your MCP client to connect to the remote server:

{
  "mcpServers": {
    "collab": {
      "url": "https://collab.mtaap.de/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

Troubleshooting

"COLLAB_API_KEY is required"

You need to set the COLLAB_API_KEY environment variable. Generate an API key at https://collab.mtaap.de/settings/api-keys

"COLLAB_BASE_URL is required"

You need to set the COLLAB_BASE_URL environment variable to your Collab webapp URL (e.g., https://collab.mtaap.de).

"Invalid API key" or "Authentication failed"

Your API key may be expired or revoked. Generate a new one at https://collab.mtaap.de/settings/api-keys

Connection issues

Ensure your firewall allows outbound connections to your Collab instance. The server performs a connectivity check on startup and will report any connection issues.

Rate limiting

The MCP API is rate limited to 100 requests per minute. If you exceed this limit, you'll receive a 429 error with a Retry-After header indicating when you can retry.

License

Proprietary - See LICENSE file for details.