MCP Integration Guide

Learn how to connect Workunit to your development tools using the Model Context Protocol (MCP)

Last updated: December 2025

Overview

The Model Context Protocol (MCP) allows AI development tools to access Workunit directly. Once connected, AI assistants can create workunits, manage tasks, organize projects, link assets, and track your development work—all without leaving your editor or chat interface.

This guide covers installation for supported tools and provides a complete reference for all available MCP tools.

Prerequisites

  • • A Workunit account (sign up at workunit.app)
  • • An MCP-compatible AI tool (Claude Code, Gemini CLI, or similar)
  • • An active internet connection

Installation

Choose your AI development tool below for specific installation instructions.

Claude Code

Run this command in your terminal:

claude mcp add --transport http workunit https://workunit.app/mcp

Verify the installation by opening Claude Code and asking:

"What Workunit tools do you have access to?"

Gemini CLI

Run this command in your terminal:

gemini mcp add --transport http workunit https://workunit.app/mcp

After installation, authenticate with:

/mcp auth workunit

Other MCP Tools

For any MCP-compatible tool, use these connection details:

Server URL:
https://workunit.app/mcp
Transport:
HTTP (Streamable)
Auth:
OAuth 2.0

Authentication

Workunit uses OAuth 2.0 for secure authentication. The first time your AI tool uses a Workunit tool, you'll be prompted to authorize access through your browser.

  1. Your AI tool will request access to Workunit
  2. A browser window opens with the OAuth authorization screen
  3. Review the permissions and click "Authorize"
  4. Return to your terminal—you're now connected!

Your authorization persists across sessions. You only need to authenticate once per tool.

Available Tools

Once connected, your AI assistant has access to the following tools. These tools work identically across all MCP-compatible clients.

System

ping

Test MCP server connectivity

Public
get_authenticated_user

Get details about the authenticated user

Auth

Projects

Projects organize related workunits and assets into logical groups.

create_project

Create a project to organize workunits and assets

Auth
get_project

Get project details with optional assets, checkins, and workunits

Auth
list_projects

List projects with optional status/owner/tag filters and pagination

Auth
update_project

Update project fields via update_mask

Auth
remove_project

Archive (preserves data) or delete (permanent) a project

Auth
project_asset_link

Link or unlink assets to/from projects

Auth

Workunits

Workunits are focused pieces of work with problem statements and success criteria.

create_workunit

Create a workunit with problem statement and success criteria. Can link initial assets

Auth
get_workunit

Get workunit details with optional tasks, assets, and AI context

Auth
update_workunit

Update workunit fields. Status=completed/archived triggers special workflows. Supports AI context fields

Auth

Tasks

Tasks break workunits into actionable items with status tracking and dependencies.

create_task

Create a task in a workunit with title, priority, and optional dependencies

Auth
get_task

Retrieve task details including status, assignee, dependencies, comments, and time logs

Auth
update_task

Update task fields including status, priority, assignment, and due date

Auth

Assets

Assets represent products, people, knowledge, and systems that your work involves.

create_asset

Create assets of any type: product, people, knowledge, or system

Auth
get_asset

Get asset details by ID with type-specific fields

Auth
update_asset

Update asset fields via update_mask. Requires asset_type specification

Auth
delete_asset

Delete an asset by ID (auto-detects type)

Auth

Troubleshooting

Connection Failed

Verify your internet connection and ensure https://workunit.app is accessible. If using a proxy or VPN, check that it allows connections to our domain.

Tools Not Available

Restart your AI tool after installation. If tools still don't appear, try removing and re-adding the MCP server. For Claude Code, use: claude mcp remove workunit && claude mcp add --transport http workunit https://workunit.app/mcp

Authentication Issues

Make sure you complete the OAuth flow in your browser. If authentication fails, check that third-party cookies are enabled for workunit.app or try in an incognito window.

Tool Errors

Most tool errors include helpful messages. Common issues: missing required fields, invalid IDs, or insufficient permissions. Check that you have access to the organization and resources you're trying to modify.