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

``bash

`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
$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 completed

State transitions: -verify_task: DRAFT -> TODO (or NEEDS_REVISION if rejected) -update_taskon 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`

`$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.

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. Callreport_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 "" --body ""2. Callreport_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.

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.

License

Proprietary - See LICENSE file for details.

Collab MCP Server

Installation

``bash

`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
$3

`$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`

`Available Tools`

`$3`

#### list_projects

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

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.

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.

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.

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.

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.

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

---

#### get_task_prompt

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.

After receiving this response: 1. Create the branch locally:git checkout -b 2. Push to remote:git push -u origin 3. Callreport_branch to inform the server

---

#### update_progress

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

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.

After receiving this response: 1. Create PR locally:gh pr create --title "" --body ""2. Callreport_pr with the PR URL and number to transition to REVIEW state

---

#### add_note

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

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.

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.

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.

Returns: { success, taskId, branchName }

---

#### report_pr

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

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.

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

---

#### approve_task

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

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`

`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`

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.

License

Proprietary - See LICENSE file for details.