GUIDE
Updated May 2026
9 topics

MCP Integration Guide

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

Jump to
OverviewPrerequisitesInstallationAuthenticationWorking across organizationsTry It OutAvailable ToolsTroubleshootingNext Steps

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.

Fast setup

Most supported tools only need one install command, then a browser-based OAuth approval.

Shared context

Every connected AI client sees the same workunits, tasks, projects, and saved context.

OAuth secured

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.

Before you run any of the commands below, sign in and open workunit.app/mcp to copy both the per-org URL and the MCP server name for the org you want to connect. Each org has its own URL (e.g. /mcp/orgs/{org_uuid}) and its own name (e.g. workunit_3615_computer) — paste them where the snippets show <your-mcp-url> and <your-mcp-name>.

Claude Code

Claude Code setup

Run this command in your terminal (replace <your-mcp-name> with the server name and <your-mcp-url> with the URL from workunit.app/mcp), then restart Claude Code if it is already open.

claude mcp add --transport http <your-mcp-name> <your-mcp-url>

OpenCode

OpenCode setup

Add the remote MCP server, then authorize it in your browser.

opencode mcp add
Location

Global

Server URL

Your per-org URL from workunit.app/mcp

Server Type

Remote over HTTP

Authentication

OAuth 2.0, no pre-registered client ID required

Then authenticate:

opencode mcp auth <your-mcp-name>
WSL2 Users

If 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 (replace <your-mcp-name> with the server name and <your-mcp-url> with the URL from workunit.app/mcp), then approve the browser authorization prompt when it appears.

codex mcp add <your-mcp-name> --url <your-mcp-url>

Gemini CLI

Gemini CLI setup

Install the server first (replace <your-mcp-name> with the server name and <your-mcp-url> with the URL from workunit.app/mcp), then authenticate from inside Gemini CLI.

gemini mcp add --transport http <your-mcp-name> <your-mcp-url>

After installation, authenticate with:

/mcp auth <your-mcp-name>

Other 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.

Server URL

Your per-org URL from 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
Tool requests access

Your MCP client asks Workunit for permission the first time it needs a protected tool.

2
Browser opens

A browser window launches to the Workunit OAuth authorization screen.

3
Approve access

Review the requested permissions and click Authorize.

4
Return to your terminal

The tool is now connected and can call Workunit over MCP.

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

Working across organizations

You can belong to as many Workunit organizations as you like — personal, work, a side project, a client. Each org has its own MCP endpoint URL. Connect one AI client per org you want to expose; the URL pins that client to that one org.

1
Find your URLs

Visit workunit.app/mcp. It lists every org you belong to with its per-org MCP endpoint URL and a copy button.

2
Connect one AI client per org

Run the install command for each org separately. Each connection uses a distinct server name from the discovery page (workunit_personal, workunit_acme, etc.), so you can tell the AI "use the workunit_acme server" and it knows exactly which connection to talk to.

3
New invitations just appear

Accept an invite in your browser and the new org shows up on workunit.app/mcp. Add a new connection from there to expose it to an AI client.

4
Removed access drops automatically

If you're removed from an org, that connection stops working immediately. Other orgs you still belong to are unaffected.

In practice

Most people connect one tool to one org. If you want to work across two orgs in the same conversation, add two MCP servers to your AI client (one per org). Because each connection has a distinct name from the discovery page, you can address them by name in your prompt — e.g. "use the workunit_acme server to list open workunits". Claude Code, OpenCode, etc. all support multiple MCP servers natively.

Try It Out

Now that your AI tool is connected, try these prompts. Every tool call lands in whichever org the MCP connection is pinned to — no need to mention the org by name in your prompt.

Verify your connection
Which workunit tools do you have access to,
and which organization am I connected to?
Create your first workunit
Create a workunit for implementing user authentication
for my app. Add clear success criteria and break it down
into tasks.
Plan work under a project
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.
Pick up where another AI left off
Search for workunits about "authentication". Show me
what's been done and what tasks are still open.
Implement an existing workunit
Get the workunit "Add password reset flow" and implement
the next open task. Update the task status when done.
Work across two orgs
If your AI client has two Workunit MCP servers configured (one per org), you can ask it to compare workunits between them by name — e.g. "use the workunit_personal server to list active work, then the workunit_acme server to do the same".
Why this matters

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.

Core Concepts

Understand workunits, tasks, assets, and how context flows between AI models

Open guide
AI Features

Learn how context atoms, multi-model handoff, and intelligent suggestions work

Open guide

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. No authentication required.

get_authenticated_user

Returns the signed-in user and every organization they belong to (id, name, role). Useful as a sanity check after install — confirms the connection works without writing anything.

Projects

Projects organize related workunits and assets into logical groups.

create_project

Create a project to organize workunits and assets in your connected org.

get_projects

Get one or more projects by ID (1-100) in your connected org, with optional stats, assets, checkins, and workunits.

list_projects

List projects in your connected org, with optional status/owner/tag filters and pagination.

update_project

Update project fields via update_mask in your connected org.

asset_link

Link or unlink assets to/from projects or workunits in your connected org. Specify project_id or workunit_id. Supports relationship_type.

Workunits

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

create_workunit

Create a workunit with problem statement and success criteria in your connected org. Can link initial assets.

get_workunits

Get one or more workunits by ID (1-100) in your connected org, with optional tasks, assets, and structured context atoms.

update_workunit

Update workunit fields in your connected org. Status=completed/archived triggers special workflows.

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, in your connected org.

get_tasks

Get one or more tasks by ID (1-100) in your connected org, with status, assignee, dependencies, and optional comments and time logs.

update_task

Update task fields including status, priority, assignment, and due date, in your connected org.

Assets

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

create_asset

Create assets of any type — product, people, knowledge, or system — in your connected org.

get_assets

Get one or more assets by ID (1-100) in your connected org. Returns full type-specific fields by default — set include_type_specific_fields=false to skip enrichment.

list_assets

List assets in your connected org, with optional asset_type/status/tag/project filters and pagination. Use project_filter="none" to find assets that aren't linked to any project.

update_asset

Update asset fields via update_mask in your connected org. Requires asset_type specification.

Directories

Organize knowledge assets into a hierarchical folder structure.

directory

Manage directories for organizing knowledge assets in your connected org. Actions: create, get, list, update, delete, move.

Context

Save and retrieve structured context atoms — the trail-of-thought for a workunit.

save_context

Save a context atom (decision, insight, question, attempt, or progress) to a workunit in your connected org.

Delete

Unified delete tool for permanently removing workunits, projects, or assets.

delete

Permanently delete an entity by ID in your connected org. Auto-detects type (workunit, project, or asset). Irreversible.

Troubleshooting

Connection failed

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.

Tools not available

Restart your AI tool after installation. If tools still do not appear, remove and re-add the MCP server, then authenticate again.

Authentication issues

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.

Tool errors

Most tool errors include a useful message. Common causes are missing required fields, invalid IDs, or insufficient permissions in the org pinned by your MCP URL.

"mcp_endpoint_moved" error

Your client is pointed at the shared /mcp endpoint, which no longer speaks the MCP protocol. Remove and re-add the server using a per-org URL from workunit.app/mcp.

"not a member of this organization"

The org URL you connected with is one you no longer belong to. Visit workunit.app/mcp to see the orgs you can connect, and re-install with the correct per-org URL.

"memberships changed; refresh required"

Your org list changed (you accepted an invite, left an org, or were removed). The MCP client should refresh its OAuth token transparently and retry. If it doesn't, restart the client — no re-auth is needed.

claude mcp remove <your-mcp-name> && claude mcp add --transport http <your-mcp-name> <your-mcp-url>
Get started free

Bring your AI agents and your team into one workspace

Workunit gives your agents structured context and your team a shared place to plan, track, and ship the work. Free to start, no credit card.

Sign up free See pricing
Keep going

Next Steps

You're connected! Here's how to get the most out of Workunit with your AI tools:

AI Features

Learn how context atoms, multi-model handoff, and intelligent suggestions accelerate your workflow

Open guide
Workunit Workflows

Master the full lifecycle — from problem statement to completion — with real-world examples

Open guide
Cloud Execution

Let AI explore your codebase and implement code changes with automatic PR creation

Open guide
Best Practices

Write better problem statements, structure tasks effectively, and keep context flowing

Open guide
Need Help?

Having trouble connecting your AI tool? Check the troubleshooting section above, or reach out to our community.

All GuidesCommunity Discussions