Model Context Protocol

You Uclusion credentials also allows you to connect your AI agent to Uclusion

Configuration

If there is a ~/.cursor folder when the Uclusion install script runs it will add itself to the mcp.json there using the installed proxy script and your workspace ID:

{
  "mcpServers": {
    "Uclusion": {
      "command": "python3",
      "args": [
        "/usr/local/bin/uclusionMCPProxy.py",
        "dd56682c-9920-417b-be46-7a30d41bc905"
      ]
    }
  }
}

The install script will do the same adding of a Uclusion mcp server to the ~/.claude.json if it is present.

For Codex (OpenAI) the config file is TOML, so if a ~/.codex directory is present the install script adds an equivalent [mcp_servers.Uclusion] table to ~/.codex/config.toml:

[mcp_servers.Uclusion]
command = "python3"
args = [
    "/usr/local/bin/uclusionMCPProxy.py",
    "dd56682c-9920-417b-be46-7a30d41bc905",
]

Unlike Cursor and Claude Code — whose config files are created automatically on first run — Codex treats config.toml as optional, so the install keys off the ~/.codex directory existing rather than the file. The managed table is delimited by # uclusion-mcp:v1 comment markers, so a later install refreshes it in place and the rest of your config.toml is left untouched. The Codex CLI runs on macOS, Windows, and Linux; only the Codex desktop app is macOS/Windows only.

Workflow rule files

The install script also offers to drop a workflow rule file in the spot each AI client looks for it. Both prompts default to N, and a subsequent install will offer to refresh in place (the Uclusion-managed block is delimited by  markers so nothing else you’ve added to the file is touched).

Claude Code: appends or refreshes the workflow block in ~/.claude/CLAUDE.md.
Cursor: writes ~/.cursor/rules/uclusion.mdc as a description:-based Cursor rule that loads whenever the prompt references a Uclusion short code (J-*, T-*, B-*).
Codex: appends or refreshes the workflow block in ~/.codex/AGENTS.md (offered only when the ~/.codex directory exists).

Both files contain the same step-by-step Uclusion job workflow — read the job, ask questions in Uclusion, make suggestions, approve, execute, and ask for review — so the AI keeps its planning, questions, and progress reports in the job instead of in chat scrollback.

Using `find_work`

You can mark jobs, bugs, or discussion as “AI able” and when your agent uses the find_work tool those items will be listed as options to begin.

Starting a session on `find_work`

A rule file can only influence a turn the AI is already taking, nothing in it makes the AI act before you send a first message. The reliable way to open a session straight into find_work is to make that the first message yourself, which both CLIs let you do as a launch argument:

Claude Code pre-fills the prompt into the input box, so you press Enter to send it:
```
claude "Run find_work"
```
Codex takes the prompt as the initial task and starts on it immediately — no Enter needed:
```
codex "Run find_work"
```

Wrap whichever you use in a shell alias so it becomes your normal way in:

alias uc='claude "Run find_work"'      # Claude Code
alias ux='codex "Run find_work"'       # Codex

Now uc (then Enter) or ux opens the AI with find_work already requested, and it answers with your numbered list of options. (Cursor is an editor rather than a prompt-on-launch CLI, so there is no equivalent there — its rule file still triggers find_work once you ask the AI to start.)

Tools

Your client loads tool definitions from the server; the Uclusion MCP server currently exposes these tools:

Tool	Description
`add_info`	Adds information to the object identified by its short code.
`approve_job_or_option`	Adds an assessment of the business value of a job or validity of an option.
`ask_question`	Creates a question with answer options about a job.
`add_options`	Adds options to a question.
`get_job`	Returns Markdown for a job (or the enclosing job when you pass a task short code) so the agent has full context: child tasks, grouped tasks, questions, suggestions, blockers, and reviews. Notes are NOT included by default — pass `include_all_resolved` true to get them (that flag also expands resolved comments instead of compressing them). The exception is a note with a reply, which is always included so the agent can see the reply. Links to content outside that job are not included. Also accepts the short code of a bug or a discussion comment that is not tied to a job.
`resolve`	Resolves a comment like a question or task or for a job moves it into Tasks Complete stage.
`make_suggestion`	Creates a suggestion that displays as created by the AI user in Uclusion. Use the suggestion tool when, instead of resolving ambiguity, you think you have found a better way.
`find_work`	Checking a job or bug or discussion as AI able will make it show in the list of work that AI uses when asking what to start.
`ask_for_review`	Creates a progress report that explains the finished work to be reviewed. Use the review tool when you need feedback on work complete enough to be tested.

These tools allow you to write a prompt like this:

Use Uclusion to get J-all-284 and also read through the application documentation at https://some.documentation.com. Then as a product manager use Uclusion to ask any questions you have about the business value of this job before adding an approval

Basic Flow

Read the installed rules file for the complete flow. Here is a summary:

Read the job. If possible read documentation and other resources explaining the software.
Ask questions. Resolve questions that you feel have been answered.
Make suggestions.
Approve the job with some level of certainty and reason that it is worth doing. Feel free to give a low certainty if the job is not well designed or providing value for customers.
When instructed to start on a task and that task’s grouped tasks. Resolve tasks that you feel are complete. Use the add_info tool at the job or task level if people need to know something important about your implementation.
If you complete a set of tasks that then has a testable output, use the ask_for_review tool to ask for feedback.

Note that most Uclusion notifications resulting from AI user actions are muted in favor AI’s own notification channel.

Knowing when to clear

As your AI client works it accumulates context — the job or comment Markdown returned by MCP and all files touched etc. None of that goes away on its own. The AI cannot reset its own context, so it will not start fresh between pieces of work unless you tell it to (in Claude Code, /clear).

The only automatic mechanism is compaction near the context limit, which summarizes older history rather than clearing it — that is lossy and leaves stale work resident until the limit is reached, so it is a safety net, not a clean handoff. Issue a /clear yourself at natural boundaries instead of relying on it.

The right boundary depends on which workflow you are in:

Single comment workflow (a view level bug or question comment). Each comment is normally self-contained and you are done after resolve. If you hand the AI a series of unrelated comments, clear between them: the previous comment’s files and decisions are irrelevant to the next one, and clearing keeps cost down and prevents the AI from conflating them. If several comments touch the same area of code, keep the context so the already-read files stay warm and the AI does not re-read them.
Job workflow (anything job or comment within a job will load the whole job). Keep the context for the life of a job — the questions, suggestions, approvals, and progress reports build on each other across steps, and clearing mid-job throws away the thread the AI is working from. Because every artifact is written back into Uclusion, though, a fresh session can reload the whole plan, so it is safe to clear between jobs after a job’s work is complete and reviewed.