Model Context Protocol

Connect your coding agent to Uclusion through the Model Context Protocol (MCP). This page covers client configuration, installation paths, optional diagnostics, and commands you can use from a terminal. For help preparing work and reviewing results, see Working with an AI agent.

The connected server supplies the current tool definitions. Use your client’s MCP tool list to inspect the tools available in your installation.

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.

The registration name is lowercase uclusion, so coding agents can discover mcp__uclusion__<tool> consistently. Updates migrate the older Uclusion registration. Restart or reconnect the client after updating.

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 public skills: uclusion and uclusion-design. You can inspect their instructions and references directly.

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. To repair missing or damaged installation files, run uclusion update from the affected project directory and restart the client.

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 ordinary codex with the installed Uclusion MCP integration. When token notes are enabled, its native adapter collects root and descendant usage, including the final response. After changing the setting, start a fresh session so the MCP connection loads it.

How many tokens Uclusion itself uses

Each usage note estimates how much of the run’s recorded content came from Uclusion. That helps you inspect the session; a with/without comparison needs two comparable measured runs. You can get the same breakdown for any Claude Code or Codex session, with or without token usage notes, by running this in the directory where the session ran:

uclusion usage

That reads the newest session started in the current directory. Pass --session with a session log path, a Claude Code session id or a Codex thread id to read a different one, and --json for machine-readable output. Nothing needs to be turned on beforehand, because the command reads the session’s own saved log. It reports that the log is gone if the client has already deleted it.

To measure a fresh interval together with local response and repeat-read statistics, name the recording file explicitly:

uclusion -e stage usage --clear --response-stats ./response-stats.jsonl
# Run the work, then read both measurements:
uclusion -e stage usage --response-stats ./response-stats.jsonl
uclusion -e stage usage --response-stats ./response-stats.jsonl --session SESSION --json

The clear command can run before any session exists. It appends a measurement_reset marker with a reset identifier and UTC cutoff; it preserves client logs, earlier JSONL rows and saved reports. It reports success only after the complete marker is written. A rejected destination, malformed statistics history, or a lock or write failure produces an explicit failure.

The next report uses the latest marker. Its token breakdown includes requests from that cutoff through one captured read endpoint, including native descendant coverage, while response statistics include captured rows after the marker. Response rows have no timestamps, so their boundary is the marker’s row position. Text and JSON show the same reset identifier, interval and source paths. Session selection still uses the newest session in this directory or the explicit --session selection. With no marker it reads the whole selected sources; plain uclusion usage continues to read the whole session.

Earlier records are replayed to reconstruct retained content. Content first read before the cutoff still costs tokens when later requests send it again. A measurement reset does not clear or compact a conversation, change configuration, reset token-audit lifecycle, or establish runtime or billed savings.

The breakdown has one line for each kind of thing Uclusion adds:

• skill and reference reads;
• the bootstrap block in CLAUDE.md or AGENTS.md;
• MCP tool definitions when the session shows which definitions were supplied;
• Poke events;
• the export command, and searches of the export;
• workflow steps that plain chat work would not have, such as reads that confirm a write or check a stage, writing the design capsule, and the completion package;
• repeat reads of content that is still in the conversation;
• Uclusion-only turns, which are requests that happen only because of Uclusion, such as restarting the Poke listener when it expires;
• the framing of MCP calls, such as headings, stage lines, links and required fields like a vote’s certainty.

The job’s own words never count, because they would be in the conversation without Uclusion too: its description, its questions and answers, and what a report says about the work. A Uclusion-only turn is the exception and counts the useful request content in full.

Optional token-audit diagnostics are excluded from this work attribution, whether their tools were used or only available. This covers the three recording tools’ definitions, arguments and replies, dedicated audit instructions, and later copies or re-sends. An ordinary mention of an audit tool name does not trigger exclusion. Requests containing both diagnostics and useful work retain the useful work. Tool activity counts apply the same boundary, so recording markers do not count as work executions.

Each line shows the tokens when content first arrives and its estimated total with later requests that send it again. Raw fresh input, cached input and output remain separate measurements. Reasoning is part of output, not an additional charge. Known measurements remain available when part of the saved history is missing, and the report explains the coverage gap.

Physical reads show delivered bytes and occurrences separately from retained content sent in later prompts. A repeated read after compaction or by a fresh helper may be required; repeated bytes alone do not establish avoidable work. Available tool definitions do not prove which definitions the provider injected into a historical request. Where the evidence is absent, injection remains unknown.

The attribution uses published artifact counts when the exact content matches, and estimates other content from its size. Saved logs do not reveal every prompt boundary or retained reasoning, so attribution remains an estimate. Raw provider counters describe the recorded consumption separately.

A weighted with/without comparison needs an explicit frozen reference profile with its published source, effective date, model, rate and context applicability. It shows each measured category and its contribution, normalizing fresh input to one and including any separately charged cache writes. Both runs must use the same profile and compatible categories, and the baseline must be positive. Missing data stays unknown. The result is a relative token metric; actual account billing and avoidable savings are separate questions.

The weighted diagnostic, uclusionTokenAudit.py breakdown --log PATH --profile PROFILE, reads the whole completed session log and eligible descendant logs. Before each comparison run, explicitly clear the response statistics with uclusion usage --clear --response-stats PATH, then start a fresh client session so each run has its own log. Save that completed log and its report before starting the next run. A statistics reset alone leaves earlier requests in an existing session log.

When served tool catalogs were recorded for the selected session, the report shows each observed version and the counting basis for its definitions. Older observations and request applicability are marked explicitly. Historical versions are separate evidence; provider injection and exact request overhead remain unknown.

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 Claude Code or Codex, 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 choice is saved in each installed Uclusion MCP connection and applies when that connection next starts. An update without either flag preserves its current setting. Start ordinary codex after updating; the former uclusion codex launcher has been retired.

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 response 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}

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. Response bodies and credentials are never recorded.

Successful reads also identify the tool, validated read target and scope in read_selector, a content_sha256 fingerprint, and a read_number. repeat_of names an earlier log row with the same read and unchanged content, or is null for a fresh read. Use it to investigate repeated note, capsule and other Uclusion reads. A repeat is a diagnostic lead; the log cannot prove that the agent did not need the information again.

Matching is separate for each conversation. context_reset event rows discard its active fingerprints after observed compaction or clear, so the next read is fresh. Earlier log rows stay available. Codex uses its native context events; Claude’s installed SessionStart and PostToolUse hooks add context and read event rows to the same file, independently of token auditing. Event rows have no byte measurements, so sum only rows with jsonrpc_utf8_bytes when comparing response sizes. context_coverage is observed when the client supplies these events and unknown when it does not, including connections without the installed hooks. Claude byte-measurement rows have connection-level candidate history because MCP does not supply Claude’s conversation identity. Use its event: read rows for the conversation history that respects compaction and clear.

uclusion -e stage usage --response-stats PATH reports response-byte totals separately from the token breakdown. It separates response read/repeat counts from Claude hook read/repeat counts, retains their observed or unknown coverage, and names the earlier rows referenced by repeats. These counts are separate evidence: Claude hooks do not add response-byte measurements, and a response row and hook row can describe the same read.

usage --clear --response-stats PATH uses the same private owned-file checks and shared writer lock as recording. Existing and newly started writers observe the appended measurement marker while preserving active repeat fingerprints, invocation deduplication and context coverage. A later repeat can still refer to a row before the marker. Only client context_reset events change that conversation history; measurement markers contain no response bytes.

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

To open a session with a request for available work, pass the prompt 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:

  codex "Run find_work"
  

A shell alias makes this your normal way in:

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

The installed Codex MCP registration carries the selected Uclusion environment. In Cursor, enter Run find_work in the chat where you want to choose work.

Using find_work

Mark a job, bug, or discussion AI able to make it available through find_work. Ask your agent for the list, then choose an item by its name, short code, or list number. If the list is empty, check that the item is marked and that the client is connected to the correct workspace.

A view can also allow agents to take available work without asking you to choose each item. See view settings to enable this, and work claims for coordinating several agents.

What you can ask your agent to do

Read job attachments when needed

Ask the agent to inspect an attachment relevant to the work. You can also list a job’s attachment names and download links from the terminal:

uclusion get_job_attachments --short-code-id J-example-1

A job with no attachments returns an empty file list. Files embedded in a description or comment retain their existing Markdown links.

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. Review the proposal before converting it, and edit its wording if the scope needs to change. 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.

Recalling past decisions

Ask about a specific topic, such as “What did we decide about report retention, and which discussions support that decision?” The agent can search the workspace export and show the relevant records with their short codes.

The export includes the discussion history and supports incremental refreshes. You can search it yourself from the terminal, or use the linked short codes to open the live records in Uclusion.

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 how to select the receiving conversation for each client.

Reviewing and clearing notifications

Ask your agent to list the notifications that need your attention, then name the job, bug, or discussion whose notifications you want cleared. You can also request this as part of finishing that work.

Clearing removes unread notifications and removes the highlight from persistent ones. See Inbox for the notification controls in Uclusion.

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.

Questions waiting for input. Check the job’s assignees when an answer does not unblock it. Questions explains the difference between primary and advisory responses and the meaning of Resolve.

Shared context. Use a Show AI view level note for information you want agents to use across jobs in that view. You can inspect and edit the note in Uclusion.

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.