MCP Integration Guide
Learn how to connect Workunit to your development tools using the Model Context Protocol (MCP)
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.
Most supported tools only need one install command, then a browser-based OAuth approval.
Every connected AI client sees the same workunits, tasks, projects, and saved context.
Access is authorized in your browser and persists across sessions for each tool.
Prerequisites
A Workunit account
Sign up at workunit.app before you connect an MCP client.
An MCP-compatible AI tool
Claude Code, OpenCode, Codex, Gemini CLI, or any other client that supports MCP over HTTP.
Internet access to workunit.app
Your client needs to reach the hosted MCP endpoint and complete the OAuth flow in the browser.
Installation
Choose your AI development tool below for specific installation instructions.
Claude Code
Claude Code setup
Run this command in your terminal, then restart Claude Code if it is already open.
claude mcp add --transport http workunit https://workunit.app/mcpOpenCode
OpenCode setup
Add the remote MCP server, then authorize it in your browser.
opencode mcp addGlobal
https://workunit.app/mcp
Remote over HTTP
OAuth 2.0, no pre-registered client ID required
Then authenticate:
opencode mcp auth workunitIf the OAuth callback fails because the browser can not reach 127.0.0.1 inside WSL, copy the full callback URL from the browser and run it manually in your WSL terminal.
curl "http://127.0.0.1:19876/mcp/oauth/callback?code=...&state=..."Codex (OpenAI)
Codex (OpenAI) setup
Add the Workunit MCP server, then approve the browser authorization prompt when it appears.
codex mcp add workunit --url https://workunit.app/mcpGemini CLI
Gemini CLI setup
Install the server first, then authenticate from inside Gemini CLI.
gemini mcp add --transport http workunit https://workunit.app/mcpAfter installation, authenticate with:
/mcp auth workunitOther MCP Tools
Other MCP Tools setup
For any MCP-compatible client, use these connection settings and follow that tool's standard remote-server setup flow.
https://workunit.app/mcp
HTTP (Streamable)
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.
Your MCP client asks Workunit for permission the first time it needs a protected tool.
A browser window launches to the Workunit OAuth authorization screen.
Review the requested permissions and click Authorize.
The tool is now connected and can call Workunit over MCP.
Your authorization persists across sessions. You only need to authenticate once per tool.
Try It Out
Now that your AI tool is connected, try these prompts to see Workunit in action. These work with any MCP-compatible client.
What Workunit tools do you have access to?I need to implement user authentication for my app.
Create a workunit for this with clear success criteria,
then break it down into tasks.I'd like to build a REST API for my blog.
Create a project called "Blog API" and add workunits
for each endpoint I'll need.Search my workunits for anything related to "authentication".
Show me what's been done and what tasks are still open.Get the workunit "Add password reset flow" and implement
the next open task. Update the task status when done.Any AI model connected via MCP sees the same workunits, tasks, and context. Start planning in Claude, implement in Codex, review in Gemini — your progress follows you everywhere.
Available Tools
Once connected, your AI assistant has access to the following tools. These tools work identically across all MCP-compatible clients.
System
pingTest MCP server connectivity
get_authenticated_userGet details about the authenticated user
Projects
Projects organize related workunits and assets into logical groups.
create_projectCreate a project to organize workunits and assets
get_projectGet project details with optional assets, checkins, and workunits
list_projectsList projects with optional status/owner/tag filters and pagination
update_projectUpdate project fields via update_mask
asset_linkLink or unlink assets to/from projects or workunits. Specify project_id or workunit_id. Supports relationship_type.
Workunits
Workunits are focused pieces of work with problem statements and success criteria.
create_workunitCreate a workunit with problem statement and success criteria. Can link initial assets
get_workunitGet workunit details with optional tasks, assets, and context atoms
update_workunitUpdate workunit fields. Status=completed/archived triggers special workflows
Tasks
Tasks break workunits into actionable items with status tracking and dependencies.
create_taskCreate a task in a workunit with title, priority, and optional dependencies
get_taskRetrieve task details including status, assignee, dependencies, comments, and time logs
update_taskUpdate task fields including status, priority, assignment, and due date
Assets
Assets represent products, people, knowledge, and systems that your work involves.
create_assetCreate assets of any type: product, people, knowledge, or system
get_assetGet asset details by ID with type-specific fields
update_assetUpdate asset fields via update_mask. Requires asset_type specification
Directories
Organize knowledge assets into a hierarchical folder structure.
directoryManage directories for organizing knowledge assets. Actions: create, get, list, update, delete, move
Search
searchSearch workunits, tasks, and assets with optional result type filtering. Use to find IDs for linking
Context
Save and retrieve structured context atoms — the trail-of-thought for a workunit.
save_contextSave a context atom (decision, insight, question, attempt, or progress) to a workunit
Delete
Unified delete tool for permanently removing workunits, projects, or assets.
deletePermanently delete an entity by ID. Auto-detects type (workunit, project, or asset). Irreversible.
Troubleshooting
Verify your internet connection and ensure https://workunit.app is reachable. If you use a proxy or VPN, confirm it allows connections to the Workunit domain.
Restart your AI tool after installation. If tools still do not appear, remove and re-add the MCP server, then authenticate again.
Complete the OAuth flow in your browser. If it fails, check whether third-party cookies are blocked for workunit.app or retry in an incognito window.
Most tool errors include a useful message. Common causes are missing required fields, invalid IDs, or insufficient permissions in the current organization.
claude mcp remove workunit && claude mcp add --transport http workunit https://workunit.app/mcpNext Steps
You're connected! Here's how to get the most out of Workunit with your AI tools:
Learn how context atoms, multi-model handoff, and intelligent suggestions accelerate your workflow
Master the full lifecycle — from problem statement to completion — with real-world examples
Let AI explore your codebase and implement code changes with automatic PR creation
Write better problem statements, structure tasks effectively, and keep context flowing
Having trouble connecting your AI tool? Check the troubleshooting section above, or reach out to our community.