MCP tools reference (Claude and Codex)

ContextRelay gives each agent a set of MCP tools so they can talk to each other and to the shared, durable ledger without leaving their own session. Claude receives its tools from the ContextRelay Claude Code plugin; Codex receives its tools after you run ctxrelay codex-mcp install.

This page is the exhaustive, agent-facing tool list. If you are wiring up automation, debugging why an agent did or did not act, or writing your own collaboration prompt, this is the surface you are working against.

Why tools instead of plain chat?

The tools are the part of an agent's behavior you can audit. A reply is a casual turn; a handoff is a recorded transfer of ownership; a record_artifact is durable evidence. Every tool call lands in the same JSONL ledger, so "what did the agents actually do" has a single, inspectable answer. See The shared durable ledger.

Claude MCP tools

Claude receives these 17 tools from the ContextRelay Claude Code plugin. They are defined in src/claude-adapter.ts.

Tool	Purpose
reply	Send a message to Codex as a new Codex turn.
get_messages	Drain queued Codex messages in pull/fallback mode.
wait_for_messages	Long-poll for Codex messages, then return the same payload as get_messages.
handoff	Record a structured handoff to Codex and deliver it live.
deliberate_with_codex	Run one bounded Claude-to-Codex deliberation and return Codex's reply for synthesis.
append_note	Add a durable Claude note to the shared ledger.
read_context	Read recent ledger entries and the latest active handoff for Claude.
session_info	Return session summary, runtime inspection, ledger counts, active handoff, autonomy, finality, and backup state.
create_session	Create a registry-backed runtime session (metadata only).
select_session	Select the registry-active runtime session for inspection.
archive_session	Archive a registry-backed runtime session.
rebind_session	Rebind a registry-backed runtime session to an existing worktree path.
task_state	Return task lanes, policy state, artifacts, and finality blockers.
record_artifact	Store a structured artifact (patch, test, command, release-gate, escalation, idle).
ask_codex_backup	Ask a read-only headless Codex backup agent for analysis. Requires autonomy enabled.
backup_status	Return current backup-agent state and the latest backup metadata.
propose_final	Record a finality proposal or auto-final decision.

Codex MCP tools

Codex receives these 16 tools after ctxrelay codex-mcp install. They are defined in src/codex-mcp.ts. The shape mirrors Claude's, with a few naming differences: Codex sends with send_to_claude and waits with wait_for_claude (rather than Claude's get_messages / wait_for_messages pair).

Tool	Purpose
send_to_claude	Send a live message to Claude through ContextRelay and record it in the ledger.
handoff_to_claude	Record a structured handoff to Claude and deliver it live.
deliberate_with_claude	Run one bounded Codex-to-Claude deliberation and return Claude's reply for synthesis.
read_context	Read recent ledger entries and the latest active handoff for Codex.
wait_for_claude	Wait for a Claude ledger reply, optionally scoped to a handoff id.
append_note	Add a durable Codex note to the shared ledger.
session_info	Return session summary, registry-backed session inspection, active handoff, and ledger counts.
create_session	Create a registry-backed runtime session (metadata only).
select_session	Select the registry-active runtime session for inspection.
archive_session	Archive a registry-backed runtime session.
rebind_session	Rebind a registry-backed runtime session to an existing worktree path.
task_state	Return task lanes, policy state, artifacts, and finality blockers.
record_artifact	Store a structured artifact.
ask_claude_backup	Ask a read-only headless Claude backup agent for analysis. Requires autonomy enabled.
backup_status	Return current backup-agent state and the latest backup metadata.
propose_final	Record a Codex finality proposal.

Codex registration is global, not per-launch

ctxrelay codex-mcp install registers a global Codex MCP server. That means a normal codex window opened inside the project can load the same tools and attach to (or start) the project's ContextRelay daemon - you do not have to launch Codex through ctxrelay codex. If you want ContextRelay participation restricted to ctxrelay codex only, run ctxrelay codex-mcp remove to drop the registration.

Backup tools require autonomy

Four tools - ask_codex_backup, ask_claude_backup, and the matching backup triggers below - only run when ContextRelay autonomy is enabled. Autonomy is off by default. Until you opt in with ctxrelay autonomy on, a backup request returns a refusal rather than spawning a worker.

Backup agents are read-only: they are spawned with restricted tools (Claude with read/search tools only, Codex in a read-only sandbox) and are meant for a second opinion or extra analysis - never for edits or git writes. This is part of ContextRelay's read-only-by-default posture. See Autonomy, idle scanner, and safe automation for the full picture.

Claude slash commands

These commands ship with the Claude Code plugin and wrap the MCP tools above, so you can drive collaboration from the prompt without remembering tool signatures.

Command	Purpose
/contextrelay:init	Create or update project-local ContextRelay config and collaboration files.
/contextrelay:status	Show session, connection, ledger, handoff, autonomy, finality, and backup state.
/contextrelay:handoff <task>	Ask Codex to take the next concrete task.
/contextrelay:review <focus>	Ask Codex for a focused read-only review.
/contextrelay:deliberate <question>	Run one bounded Claude–Codex deliberation and synthesize the result.
/contextrelay:finalize	Prepare a finality proposal from current ledger evidence.
/contextrelay:on [session name]	Activate ContextRelay for this session. Deterministic; runs ctxrelay attach.
/contextrelay:off	Deactivate ContextRelay for this session. Deterministic; runs ctxrelay detach.

/contextrelay:on and /contextrelay:off are about activation, not tools

These two commands toggle whether ContextRelay is active for the current session - they run ctxrelay attach and ctxrelay detach under the hood. They matter when you run ContextRelay dormant-by-default and want to opt a single session back in.

Codex fallback markers

When Codex's MCP tools are not available (for example, before ctxrelay codex-mcp install, or in a Codex client that has not loaded the registration), Codex can still participate by placing a marker at the very start of a message. ContextRelay parses these markers from the transcript and routes them as if the matching tool had been called.

[IMPORTANT] CONTEXTRELAY_READ_CONTEXT: <optional focus>
[IMPORTANT] CONTEXTRELAY_TASK_STATE
[IMPORTANT] CONTEXTRELAY_NOTE: <note>
[IMPORTANT] CONTEXTRELAY_ARTIFACT:
kind: patch_summary|release_gate|test_report|command_log|escalation_suggestion|idle_opportunity|idle_action_result|idle_fleet_result|idle_evaluation_result|idle_write_result
title: <short title>
summary: <what happened>
status: passed|failed|blocked|unknown|skipped|timed_out
evidence:
- <optional evidence>
[IMPORTANT] CONTEXTRELAY_HANDOFF_TO_CLAUDE: <ask>
[IMPORTANT] CONTEXTRELAY_PROPOSE_FINAL:
summary: <what is complete>
evidence: <why it is complete>
remaining_risk: <optional risk>
handles_handoff_id: <optional handoff id or comma-separated ids>
[IMPORTANT] DONE: <summary>
[HUMAN] <human-directed side note that should not be delivered to Claude as work context>

Two notes on the markers above:

• [HUMAN] is not a tool. It tags a side comment so ContextRelay does not deliver it to Claude as actionable work context - useful for talking to the human in the transcript without creating a task for the peer agent.
• Backup triggers are explicit and, like the backup tools, require autonomy:

[IMPORTANT] ASK_CLAUDE_BACKUP: <read-only help request>
[IMPORTANT] ASK_CODEX_BACKUP: <read-only help request>

Artifact kinds and statuses

record_artifact (and the CONTEXTRELAY_ARTIFACT marker) accept a fixed set of kind and status values, defined in src/types.ts. Use them so the viewer and task board can categorize evidence consistently.

Kinds:

patch_summary
release_gate
test_report
command_log
escalation_suggestion
idle_opportunity
idle_action_result
idle_fleet_result
idle_evaluation_result
idle_write_result

Statuses:

passed
failed
blocked
unknown
skipped
timed_out

Pick the narrowest tool that fits

A loose convention that keeps the ledger readable: use reply for conversation, append_note for a durable decision or fact, handoff / handoff_to_claude to transfer a concrete task, record_artifact for evidence (a diff, a test run, a gate result), and propose_final only when work is actually complete. See Handoffs, replies, and deliberation.

Next steps

• Handoffs, replies, and deliberation - when to reach for each collaboration tool.
• CLI command reference - the human-facing commands, including ctxrelay codex-mcp and ctxrelay autonomy.
• config.json reference - where coordinator, autonomy, and permission settings live.