Model Context Protocol (MCP) server for AI agents to interact with Collab - the multi-tenant collaborative agent development platform
npm install @mtaap/mcpModel 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.
``bashInstall globally
npm install -g @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
$3
| 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) |$3
| Variable | Description |
|----------|-------------|
|
COLLAB_DEBUG | Set to true to enable debug logging |$3
`bash
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 completedState 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 -> TODOAvailable Tools
$3
#### 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 }---
$3
#### 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 }---
$3
#### 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.---
$3
#### 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:
`json
{
"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 "
}
`After receiving this response:
1. Create the branch locally:
git checkout -b
2. Push to remote: git push -u origin
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:
`json
{
"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 "
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 }---
$3
#### 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.---
$3
#### 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.---
$3
#### 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
$3
`
create_task -> get_task_prompt (DRAFT) -> verify_task(approved=true) -> task moves to TODO
`$3
`
list_projects -> get_project_context -> list_tasks(state=TODO) -> get_task -> get_task_prompt (TODO)
-> assign_task (returns suggested branch name)
-> git checkout -b (local git command)
-> git push -u origin (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)
`$3
`
check_active_task -> (if active) get_task -> get_task_prompt (IN_PROGRESS) -> update_progress -> complete_task
`$3
`
list_tasks(state=REVIEW) -> get_task -> approve_task OR request_changes
`$3
`
report_error -> abandon_task -> list_tasks -> assign_task (retry or pick different task)
`Usage
There are two ways to use the Collab MCP server:
$3
Install and run locally using stdio transport:
1. Configure your environment variables
2. Add to your MCP client configuration (Claude Desktop, OpenCode, etc.):
`json
{
"mcpServers": {
"collab": {
"command": "npx",
"args": ["-p", "@mtaap/mcp", "collab-mcp"],
"env": {
"COLLAB_BASE_URL": "https://collab.mtaap.de",
"COLLAB_API_KEY": "your-api-key"
}
}
}
}
`3. Use the tools from your AI agent
$3
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:
`json
{
"mcpServers": {
"collab": {
"url": "https://collab.mtaap.de/mcp",
"headers": {
"X-API-Key": "your-api-key"
}
}
}
}
`Troubleshooting
$3
You need to set the
COLLAB_API_KEY environment variable. Generate an API key at https://collab.mtaap.de/settings/api-keys$3
You need to set the
COLLAB_BASE_URL environment variable to your Collab webapp URL (e.g., https://collab.mtaap.de).$3
Your API key may be expired or revoked. Generate a new one at https://collab.mtaap.de/settings/api-keys
$3
Ensure your firewall allows outbound connections to your Collab instance. The server performs a connectivity check on startup and will report any connection issues.
$3
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.Proprietary - See LICENSE file for details.