Model Context Protocol

Connecting a coding agent gives it Uclusion’s tools through the Model Context Protocol (MCP) and installs a workflow that tells it when to use them. This page covers what gets installed, the options you can turn on, how to start a session, what you can ask your agent to do, and how to read what it shows you. What the workflow makes the agent do is described in What the agent workflow controls. Your agent loads its tool definitions directly from the Uclusion server, so this page does not list them.

Configuration

For a new account, your coding agent can create and connect the workspace through the agent-led setup flow. The manual setup below is for existing workspaces and as a fallback.

The Uclusion install script registers Uclusion as an MCP server in each client it finds:

• Cursor, when ~/.cursor exists, in ~/.cursor/mcp.json.
• Claude Code, when ~/.claude.json exists, in that file.
• Codex, when ~/.codex exists, in ~/.codex/config.toml. Codex treats that file as optional, so the install checks for the directory rather than the file.

Each entry runs the installed proxy with your workspace ID. For Cursor and Claude Code:

{
  "mcpServers": {
    "Uclusion": {
      "command": "python3",
      "args": [
        "/usr/local/bin/uclusionMCPProxy.py",
        "<your workspace ID>"
      ]
    }
  }
}

For Codex:

[mcp_servers.Uclusion]
command = "python3"
args = [
    "/usr/local/bin/uclusionMCPProxy.py",
    "<your workspace ID>",
]

The Codex table sits between # uclusion-mcp:v1 comment markers, so a later install refreshes it in place and leaves the rest of config.toml alone.

What gets installed

Besides the MCP server, the install adds two things to each client:

• A short resident block in the client’s instructions file. It is loaded in every session, so the agent can connect to Poke AI delivery and recognize Uclusion work when it comes up.
• Two skills: uclusion, the job workflow, and uclusion-design, which writes and checks design capsules. They load only when Uclusion work comes up, so unrelated coding sessions do not carry them.

uclusion update refreshes all of it. Setup and updates replace only Uclusion’s marked block in an existing CLAUDE.md or AGENTS.md and leave the rest of the file as you wrote it. When a Codex AGENTS.override.md has content, that is the file Codex reads, so the block goes there instead. CODEX_HOME moves the Codex configuration and global block, while Codex’s user skills stay under ~/.agents/skills. A skill folder of the same name without Uclusion’s marker is treated as yours and is never overwritten. If the block or either skill is missing or damaged, the agent reports a broken install and asks to run uclusion update rather than working around it.

A project install requested in your home directory is the global install, because the home directory’s project paths are the global ones or sit beside them. Setup does the global install and says so, and uclusion update never treats the home directory as a project. If an earlier project install there left a Uclusion entry in ~/.mcp.json, or Uclusion’s token-audit settings in ~/.claude/settings.local.json, the global install removes them and lists what it removed, leaving everything else in those files as it was.

Options you can turn on

Each option below is off until you turn it on. The uclusion update commands change the global install and the project install for the directory you run them in, when there is one, so run them from the project when you want its install changed too. Omitting an option’s flags keeps each install’s current setting. For a non-production environment, put its option before the subcommand, for example uclusion -e stage update --token-audit. Restart the affected agent sessions, or reconnect their Uclusion MCP servers, so a change loads.

Token usage notes

Token usage notes record how many tokens your agent spent on a job, broken down by the kind of work. They work with Claude Code and Codex. Turn them on in the setup page, or from the terminal:

uclusion update --token-audit

and off with:

uclusion update --no-token-audit

Turning them off removes only the Claude settings and hooks Uclusion wrote.

While they are on, the agent measures its work on a job from when it starts to a blocker, a review handoff or completion, and adds a usage note to the job with the total and a breakdown by phase. The default phases are planning, implementation, testing and other. You can ask the agent to use labels that suit the job instead, such as web searches, source review and copywriting. The note is updated as each phase ends, so an interrupted run keeps every phase that had finished, and missing data is labelled partial rather than presented as complete. For totals across jobs, ask the agent: it reads the notes from the workspace export and adds them up. There is no separate dashboard.

Only token counts are recorded. Prompt and response text is not copied into the note. Collected data stays on your machine until it is delivered, is deleted seven days after delivery, and is kept for at most 30 days when it cannot be delivered.

Claude Code. Uclusion reads Claude’s local OpenTelemetry log stream, bound to localhost, with prompt, response, tool-content and raw API body logging turned off. If your Claude settings already have a telemetry or content policy of your own, the installer keeps it and reads usage from Claude’s local transcript instead, which can be less complete after upgrades, compaction or interrupted sessions. Both ways need Claude’s hooks. If your settings contain "disableAllHooks": true, the installer leaves that alone and warns that token notes are not on. Remove it or set it to false, rerun setup, and restart Claude Code.

Codex. Start each session you want measured with uclusion codex. A plain codex launch still has Uclusion’s tools but collects no usage, and collection cannot be added to a Codex session that is already running.

Work claims

If several agents find work on their own, the work claim lock stops two of them starting the same job or bug. Turn it on with uclusion update --work-claims and off with uclusion update --no-work-claims. The opt-in work claim lock explains how it works.

Local response-size statistics

You can record how many bytes each MCP response returns to your agent, without any of the content, in a local JSONL file. This shows how much of your agent’s context Uclusion uses.

For one Codex launch, pass the option before codex. It is not saved as a setting:

uclusion --response-stats ./response-stats.jsonl codex

For Claude Code, turn recording on or off through an update:

uclusion update --response-stats ./response-stats.jsonl
uclusion update --no-response-stats

A relative path is resolved from the directory where you run the command.

The disposable AI demo takes the same option on its install command, for Claude Code or Codex:

curl -fsSL https://production.uclusion.com/scripts/install.sh | bash -s -- demo --clients claude --response-stats ./evaluator-stats.jsonl

Only the evaluating agent’s connection records, not the workshop owner’s. The file stays where you put it, so removing the demo leaves it unless it is inside the demo directory.

Each message sent to your agent adds one row. For example, with illustrative numbers:

{"method":"tools/call","tool":"get_job","scope":"thread_only","status":"ok","jsonrpc_utf8_bytes":251,"text_utf8_bytes":80}

Those are the only six fields. scope is default, sections or thread_only for a get_job read, and otherwise null. status is ok, tool_error, rpc_error or notification. jsonrpc_utf8_bytes is the size of the whole message and text_utf8_bytes the size of its text content. Neither is a count of provider tokens or of billed savings. IDs, arguments, response bodies and credentials are never recorded.

Choose a file in a directory that already exists. Recording writes only to that file, which must be yours alone, and never creates directories, rotates files or sends anything anywhere. It needs POSIX file ownership checks, so it is not available on Windows. If recording fails, a notice says it has stopped and MCP carries on normally.

Starting a session on find_work

Your agent acts only when you send it a message. When a session has no work assigned, the installed workflow has the agent call find_work in response to your first message, whatever it is. You can make find_work that first message by passing it when you launch the agent:

• Claude Code puts the prompt in the input box, so you press Enter to send it:

  claude "Run find_work"
  

• Codex starts on the prompt immediately:

  uclusion codex -- "Run find_work"
  

A shell alias makes this your normal way in:

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

For non-production Codex, add the environment before codex, for example uclusion -e stage codex -- "Run find_work". Cursor is an editor rather than a command you launch with a prompt, so it has no equivalent. Its rule file has the agent call find_work at the start of an unassigned session.

Using find_work

Mark jobs, bugs or discussion as “AI able” and they appear in your agent’s find_work list. The agent shows the whole list, numbered, with each item’s short code and name, and each bug’s priority: critical, normal or minor. You choose what it works on.

In a brand-new workspace, the first session’s empty list comes with one-time onboarding, which the agent follows straight away. After that, an empty list makes the agent offer instructions for adding and working on a job.

A view can also let agents take the next available work from this view without asking. The agent still shows the whole list, then starts the first item marked for it in the same turn. It never interrupts work in progress or starts an unmarked item, and a direct instruction from you comes first. It can only do this inside a turn it is already taking, so it does not wake an idle agent. The Views documentation explains where to turn it on.

What you can ask your agent to do

Gather existing work into a new job

Ask your agent to create a job from existing items and it moves them into the new job as it creates it:

• Standalone bugs become tasks of the new job.
• Tasks in other jobs move out of those jobs. This is how you defer work out of a job you want to close without losing its history. A grouped task arrives as a top level task.
• Suggestions in a view arrive still as suggestions, so you can gather several in one place and then convert or resolve each one.

You can add new tasks in the same request. Each item keeps its short code, discussion, attachments and resolution state, so anything that referred to it still points at it. Replies follow a moment later.

When the moved tasks come from jobs that share a stage that allows assignment, such as Doable, the new job starts in that stage, so work that already had permission keeps it. Otherwise the new job starts in the workspace’s initial stage.

The agent reports each item as moved, failed with the reason, or unconfirmed. Unconfirmed means the move may or may not have happened, so check the new job before asking again: each request creates another job. One item failing does not stop the others, and nothing moves if the job itself cannot be created. This only creates new jobs. Moving an item into a job that already exists is done in Uclusion itself.

Move a task out to a bug

When a task turns out to be lower value than the rest of its job, or needs its own context, ask your agent to move it out to a bug and say how severe it is: critical, normal or minor. It becomes a bug in the view with the same short code, body, author and replies. A grouped task becomes a top level bug.

Turn a suggestion into a task

When you decide a suggestion on a job is work to do, ask your agent to make it a task of that job, as Move to task does in Uclusion. It keeps its short code, body and discussion. The agent does this only when you ask, and never converts its own suggestions on its own judgment. A suggestion in a view has no job to join, so gather it into a new job first. A suggestion on an option inside a question stays with that question.

Converting an AI suggestion accepts its proposal as written. The agent does not ask you to choose those same details again unless evidence discovered after conversion bears on them; its question then names that evidence.

When the agent moves work without asking

Moves happen when you ask for them, with one exception. When a finished task is not related enough to the rest of its job to share its review, the agent moves it into a job of its own, so it is reviewed there without waiting for the others, and says why in that review. Otherwise an agent that thinks a task belongs elsewhere makes a suggestion naming the task and its reason, and moves it once you accept.

Recalling past decisions

Chat scrollback disappears when a context window clears, but every question, option, vote and reason in your workspace persists. Before reopening a settled debate, or whenever it needs to know whether something was already decided, the agent runs uclusion export and searches the result. Because it has the full contents locally, it shows what it found, with the details, right in the conversation. You follow a short code into Uclusion only when you want the live item. The export is incremental, so refreshing it takes seconds, and a fresh session, or a different agent entirely, can recall decisions it was never part of.

Poke AI

Uclusion can prompt your connected agent directly. A Poke AI button sends Start <short code>, and once the agent has taken part in a job, changes to it arrive as Added, Updated and Responded messages, so the agent picks up your answers without you repeating them in chat. Poke AI covers the buttons, the message forms and what running several agents requires. Cursor’s IDE chat cannot receive them, so there you start the agent’s next turn yourself.

Reviewing and clearing notifications

Ask your agent what needs your attention and it lists your notifications for the workspace, most urgent first, each with the short code it is about. When the agent finishes a piece of work, clearing that work’s notifications is part of its completion package, so you choose it along with committing and pushing. The clear also carries the package’s final record, which Uclusion posts silently just before clearing. Outside that package, it asks before clearing the notifications for a particular item. Clearing works as it does in Uclusion: unread notifications are removed and persistent ones lose their highlight. There is deliberately no way to clear everything at once, because that could discard notifications that arrived after you agreed.

Reading what your agent shows you

Codes inside a question. Options, votes, suggestions, replies and Info inside a question are numbered per question, so O-1 appears in every question. Your agent shows each one prefixed with its question’s code, such as Q-example-1_O-1, and you can use that form when you refer to one.

Who can answer the agent’s questions. Each record the agent reads has a header saying what kind of author wrote it: From AI user:, From authoritative human: or From advisory human:. It names the kind of author, never the person. On a job, the job’s current assignees answer the agent’s questions. Their clear reply, or their For vote on an option, makes the question answerable, and the job stays in Requires Input until the agent resolves it. Replies and votes from anyone else show as advisory. The agent still sees them and may change its view, but they do not unlock the job. Anyone can instead resolve the question directly, which hands the choice back to the agent and returns the job to its previous stage. A question in a view has no assignees, so anyone’s clear reply or For vote answers it.

The agent’s own notes. The agent keeps general lessons in a Show AI view level note rather than in private memory. Everyone in the view is notified when it creates or changes one, and you can edit it. The agent treats your edits as authoritative.

Running operations yourself

The installed uclusion command can do anything your agent can do through MCP, so you can script Uclusion from a terminal or a CI job. uclusion -help lists its commands, and uclusion <command> -h lists a command’s flags. For a non-production environment, put its option first, for example uclusion -e stage find_work.

Knowing when to clear

Your agent accumulates context as it works: the job and comment Markdown it reads and every file it touches. It cannot reset its own context, so it starts fresh only when you tell it to, for example with /clear in Claude Code. Compaction near the context limit summarizes older history rather than clearing it, so treat it as a safety net rather than a clean handoff.

The right moment depends on the work:

• A single comment, such as a bug or question in a view, is usually self-contained, so clear once it is resolved if the next item is unrelated. If several comments touch the same code, keep the context so the files the agent already read stay warm. A bug that needs a decision between options becomes a job you own, and the agent carries on there.
• A job builds up questions, suggestions and reviews that depend on each other, so keep the context for the life of the job. Everything is written back to Uclusion, so it is safe to clear between jobs once a job’s work is complete and reviewed.

The agent offers a clear at these moments and stays quiet mid-job. The offer is a reminder: you can clear whenever you like, and declining costs nothing.