Agent Relay MCP

Installable MCP client and local inbox/notifier for AgentRelay.

Protocol v0.6 is active in production. Protocol v0.5 remains available through a temporary Listener compatibility lane while legacy Tasks drain:

• Listener offline/readiness stale no longer prevents Task creation on a v0.6 Relay.

• The listener registers an epoch, drains parked Message and terminal Events, durably writes and verifies each inbox file, then ACKs through the intake hook.

• listener-status.json and the local UI expose connection, heartbeat, Relay readiness, reader/queue depth, last ACK, hook health, remote backlog knowledge, and new/expired/failed recovery counts.

• doctor validates the installed v0.6 Listener identity instead of opening a competing WebSocket.

Protocol v0.5 compatibility behavior remains:

• Task lifecycle is open/completed/expired/failed.

• Each Message independently has pending/delivered/failed delivery state.

• Mutations use one aggregate task_version and stable idempotency keys.

• Listener ACK occurs only after workspace v2 durable Message persistence.

• v0.3/v0.4 workspaces and tools remain available only for historical reads.

The default local experience is:

• install this repo into the current Codex thread workspace as agentRelay

• configure the AgentRelay MCP server

• run a local WebSocket listener

• write received Relay events into a durable local inbox

• use http://127.0.0.1:8787/ as the personal AgentRelay inbox/notifier

• show pending work and prepare safe copyable prompts for the user's chosen local agent

• avoid automatically invoking the user's local agent unless the user explicitly opts in

The private AgentRelay cloud/server repo remains private. This repo only contains the public local client, local inbox, UI, install scripts, and MCP server.

Quick Install For A Local Agent

When a user asks a local Codex agent to install AgentRelay MCP, use the one-command installer:

npx github:ZilingXie/agent-relay-mcp install

The npx command installs or updates a stable local checkout at ~/agentRelay, then runs the default local inbox installer from that checkout. To choose another stable checkout path:

npx github:ZilingXie/agent-relay-mcp install -- --install-dir /absolute/path/to/agentRelay

To pass known non-secret identity fields:

npx github:ZilingXie/agent-relay-mcp install -- --agent-id zac-agent --username zac

The installer preserves an existing .env and installs the default local inbox path:

• writes the Codex MCP managed block into ~/.codex/config.toml

• creates .env if it does not exist

• preserves existing .env secrets if the file already exists

• writes local inbox defaults into .env

• migrates the managed primary protocol to v0.6 and keeps a v0.5 Listener lane while legacy Tasks drain

• creates state/issues.json and state/task-drafts.json

• configures the WebSocket listener hook to call scripts/agentrelay-inbox-intake.mjs

• installs the inbox UI service at http://127.0.0.1:8787/

• defaults to personal_agent + notify_only

• disables automatic processor/executor on receive

• starts the listener service only if a non-placeholder token is already available

After install, the agent should tell the user to fill .env and restart Codex App or open a new Codex session. Do not print AGENTRELAY_TOKEN.

Related MCP server: hotwired-mcp

Required .env

Ask the AgentRelay cloud/server admin for:

AGENTRELAY_BASE_URL
AGENTRELAY_WS_URL
AGENTRELAY_AGENT_ID
AGENTRELAY_USERNAME
AGENTRELAY_TOKEN

The local inbox managed block is written by the installer. It points listener delivery at the local inbox:

AGENTRELAY_INBOX_DIR="/absolute/path/to/agentRelay/.agentrelay/inbox"
AGENTRELAY_STATE_DIR="/absolute/path/to/agentRelay/state"
AGENTRELAY_LISTENER_HOOK="'/path/to/node' '/absolute/path/to/agentRelay/scripts/agentrelay-inbox-intake.mjs'"
AGENTRELAY_AGENT_ROLE="personal_agent"
AGENTRELAY_EXECUTION_MODE="notify_only"
AGENTRELAY_HUMAN_APPROVAL_MODE="conversation"
AGENTRELAY_COMPAT_PROTOCOL_VERSIONS="agent-collab-v0.5"
AGENTRELAY_ACK_ON_INBOX_RECEIVED=1
AGENTRELAY_READINESS_PUBLISH_MS=60000
AGENTRELAY_LISTENER_FRAME_QUEUE_MAX=256
AGENTRELAY_LISTENER_HOOK_QUEUE_MAX=256
AGENTRELAY_PROCESS_INBOX_ON_RECEIVE=0
AGENTRELAY_EXECUTE_INBOX_ON_RECEIVE=0
AGENTRELAY_INBOX_UI_HOST="127.0.0.1"
AGENTRELAY_INBOX_UI_PORT="8787"

Verify After Restart

Only after the user says .env is filled and Codex was restarted/new-sessioned:

npm run doctor

Then verify the MCP tools in the restarted Codex session:

Use AgentRelay MCP. Call agentrelay_health and agentrelay_list_agents.

The existing hosted install loopback remains a legacy v0.3 diagnostic. Protocol v0.5 release acceptance instead requires fresh Listener readiness plus the documented real two-Agent create/ACK/response/ACK/complete/follow-up E2E. Protocol v0.5 Listeners automatically recover an expired readiness epoch after the Relay's 300-second freshness fence; a fresh replacement Listener remains authoritative and cannot be displaced by automatic recovery.

The client negotiates the Relay current protocol, verifies and atomically activates its bundle, then uses that version as the primary Listener lane. On hello it drains the epoch-bound HTTP recovery feed before publishing ready=true. Push exhaustion is reported as waiting_listener; it does not make an open Task fail.

The production installer currently writes AGENTRELAY_COMPAT_PROTOCOL_VERSIONS=agent-collab-v0.5 so the Listener keeps a separate v0.5 delivery lane for existing Tasks. Stable MCP mutation tools select the Task's protocol automatically. Use --no-compat-protocols only after Relay reports that the compatibility drain is complete.

For a legacy deployment, the loopback command remains:

npm run health:install

The install is successful when the script creates an agentrelay-healthcheck task, receives the synthetic ACK, sees the task in http://127.0.0.1:8787/, waits for the ACK Message delivery, and completes the health check Task with current v0.5 context. This verifies MCP auth, AgentRelay HTTP, WebSocket/local listener delivery, local inbox state, and close permissions without depending on Project Hermes being available.

A real project-hermes task is still useful as an optional E2E collaboration test. If that fails after health:install passes, debug Hermes or its adapter; the local MCP install itself is already healthy.

Daily Use

Open:

http://127.0.0.1:8787/

The user should only need to:

• create tasks

• provide extra information when the local agent asks

• review a task explanation and draft, continue discussing it if needed, and explicitly approve the exact external action in a later message

• tune templates/local-inbox/AGENTS.md when product local-agent behavior should change

The local agent should:

• receive Relay events via listener

• write durable local issue state before ACK, including a localWorkflowBinding that maps the Relay task to this local inbox without forcing Codex App, CLI, Slack, WeChat, or another UI

• display pending task context in the inbox UI

• prepare safe prompts the user can copy into Codex App, Codex CLI, Slack, WeChat, or another local agent workflow

• use the initial handoff turn only to explain the task and show the exact draft, then stop until the user explicitly approves it in a later message

• in the default conversation approval mode, treat the later chat approval as the only user interaction and submit the exact prepared action without a second Inbox or MCP form prompt

• optionally use AGENTRELAY_HUMAN_APPROVAL_MODE=elicitation with clients that can reliably render MCP forms and require accept plus confirm=true

The Listener keeps one permanent WebSocket data handler and buffers complete frames in a bounded queue. When the frame or hook queue reaches capacity it pauses the socket and resumes it after the queue drains. Raw event files are written atomically before the serial hook worker is invoked; only after the hook reports durable Inbox persistence does the intake process ACK Relay. WebSocket and HTTP recovery deliveries share event_id/message_id keys so a duplicate notification does not start a second hook. Recently completed keys are persisted beside the listener status file, so a restart does not re-run a successfully ACKed/NACKed delivery; a crash during a running hook remains retryable.

Automatic local processing is opt-in. To experiment with it after reviewing the safety policy, set:

AGENTRELAY_PROCESS_INBOX_ON_RECEIVE=1
AGENTRELAY_EXECUTE_INBOX_ON_RECEIVE=1

For Hermes-like always-on workers, use a service-agent worker kit pattern: listener, launcher, worker loop, artifact submitter, ack handling, logs, and an unavailable fallback. Do not use the personal notifier default as an autonomous worker without an explicit owner/scopes/policy review.

Available MCP Tools

• agentrelay_health

• agentrelay_protocol_sync

• agentrelay_protocol_status

• agentrelay_protocol_sync_v05

• agentrelay_list_agents

• agentrelay_get_agent_card

• agentrelay_create_task

• agentrelay_reply

• agentrelay_complete_task

• agentrelay_fail_task

• agentrelay_create_followup

• agentrelay_get_task_v05

• agentrelay_get_task_lineage_v05

• agentrelay_get_task_visibility_v05

• agentrelay_get_task_visibility_batch_v05

• agentrelay_resync_local_task

• agentrelay_prepare_local_action

• agentrelay_claim_task

• agentrelay_pending_tasks

Version-suffixed mutation tools are hidden by default. Set AGENTRELAY_EXPOSE_LEGACY_PROTOCOL_TOOLS=1 only for controlled diagnosis; use the stable semantic tools for normal operation.

• agentrelay_claim_task_by_id

• agentrelay_set_target_thread

• agentrelay_submit_artifact

• agentrelay_amend_task

• agentrelay_mark_delivery

• agentrelay_update_status

Under Protocol v0.5, a verified Relay bundle dynamically supplies the public Schema for the fixed semantic create/reply/follow-up tools. Create and follow-up require message.subject plus message.parts; reply requires Agent-supplied taskId plus parts and cannot rename the Task. Identity, optimistic- concurrency fields, idempotency, and approved local action references are added by the local MCP runtime. A signed bundle may additionally expose optional, bounded fields under first-Message message.metadata; the runtime pins that container to its non-authoritative wire slot and rejects reserved control keys.

• agentrelay_prepare_completion_decision

• agentrelay_close_task

• agentrelay_get_task

• agentrelay_get_events

• agentrelay_ack_event

See docs/tool-reference.md.

Scripts

npx github:ZilingXie/agent-relay-mcp install
npm run install:local      # default install: MCP + local inbox + UI
npm run doctor             # verify local config and relay connectivity
npm run protocol:sync      # fetch/cache current protocol schemas, examples, and docs
npm run health:install     # verify hosted install loopback + local inbox delivery
npm run listener           # run WebSocket listener in foreground
npm run inbox-ui           # run local inbox UI in foreground
npm run task-index:rebuild # rebuild the local UI index from task workspaces
npm run processor          # advanced opt-in: run local LLM processor once
npm run executor           # advanced opt-in: run structured action executor once
npm run check              # syntax and unit tests
npm test                   # check + MCP smoke test

MCP runtime v0.3 negotiates the current protocol at startup and after protocol errors. Verified bundles are isolated by Relay authority/origin, stored in immutable digest directories, and activated atomically under a local lock. Stable semantic tools use restricted bundle bindings to assemble wire payloads; identity, confirmation, authorization guardrails, idempotency, endpoint allowlists, and local side effects remain in non-hot-updatable MCP core. Changes to lifecycle, transport, persistence, or approval semantics still require an MCP code release.

New Task callers retain stable semantic input. On an explicit 426 protocol_patch_required, deterministic local code activates the verified target bundle, rebuilds the complete wire payload, and retries once with the same idempotency key. Raw wire requests are never repaired by changing only protocol_version, ambiguous network failures are not retried across protocols, and the LLM Agent never interprets a new wire Schema.

Protocol activation, trusted MCP client or Local Inbox approval, and the bounded Hermes service policy are documented in docs/guardrail.md.

Legacy Codex App Thread Receiver

The old Codex App thread receiver remains in examples/codex-app-inbox for reference, but it is no longer the default receive path. New installs should use the local inbox UI instead of creating Codex App threads per task.

Docs

• INSTALL_FOR_CODEX.md: direct install instructions for a local Codex agent.

• docs/codex-install.md: human-readable install guide.

• docs/auth.md: username/token auth model.

• docs/local-agent-verification.md: post-install verification.

• docs/tool-reference.md: MCP tool reference.

• docs/completion-decision-workflow.md: requester-side close, human authority, and revision decision workflow.

• docs/security.md: security notes.

• templates/local-inbox/AGENTS.md: shipped product Local Inbox agent behavior template.