Connect Claude Code to AgenTrux

Claude Code (CLI) connects to AgenTrux as an MCP client, like any other OAuth-aware client. What makes it worth its own page is channels: with channels enabled, new Topic events are pushed into an idle Claude Code session and Claude reacts without human input — no polling loop. That turns a Claude Code session into a resident agent that answers requests arriving on a Topic.

This page covers the connection steps and the channels setup. For the tool reference (publish_event, read_events, …), error handling, and the OAuth details shared by all MCP clients, see the MCP Server doc.

Prerequisites

• Claude Code 2.1.x (the channels feature was verified with 2.1.241)
• An MCP connection URL, issued from the Script page in the Console

Connect (two commands)

claude mcp add --scope user --transport http agentrux https://api.agentrux.com/mcp/c/your-connection-id
claude mcp login agentrux

claude mcp login opens your browser with the AgenTrux sign-in and consent screen. After approving, the terminal prints:

Authenticated with "agentrux". Its tools are now available in Claude Code.

Inside an interactive session you can alternatively use the /mcp panel and choose Authenticate. Once connected, all AgenTrux tools are available; see the tool list.

Real-time events with channels (research preview)

Why channels are special

Claude Code does not surface arbitrary MCP server notifications to the model — custom notification methods are silently discarded. The one mechanism that reaches the model is a channel message: it is injected into the running session's context, and Claude reacts to it even when the session is idle.

The AgenTrux MCP server supports this. When a new event arrives on a Topic your Script can read, the server pushes a channel notification into your session. The notification is a pointer only (topic and event id) — the event body is fetched with read_events, so read permissions and metering apply as usual.

Channels is a research preview feature on the Claude Code side and requires the setup below.

Managed settings (conditional)

Needed when your Claude account belongs to a Team/Enterprise organization or your machine has managed settings deployed (per the official Claude Code docs, Pro/Max accounts without an organization can skip this step). macOS example, once:

sudo mkdir -p "/Library/Application Support/ClaudeCode"
printf '{"channelsEnabled": true}\n' | sudo tee "/Library/Application Support/ClaudeCode/managed-settings.json"

Launch with the channel enabled

Currently via the development flag:

claude --dangerously-load-development-channels server:agentrux

Choose "I am using this for local development" at the confirmation prompt.

Notes

• In environments where the managed setting is required but missing, notifications are silently dropped (no error is shown)
• Non-interactive mode (claude -p) cannot show the confirmation dialog and therefore cannot use channels
• Events pushed while the session is closed are not replayed; catch up with the read_events cursor after restarting
• Notifications are pointers only; fetch the body with read_events

Running Claude Code as a resident worker

With channels active, a simple prompt turns the session into an always-on worker:

1. Launch with the channel flag (above) in a persistent terminal
2. Give Claude the ground rules for the Topic, for example:
   • react only to events whose event_type is task (ignore reply / result so it never answers itself)
   • publish the answer back to the same Topic with event_type: "reply"
3. Leave the session open — each pushed event triggers a read → process → publish cycle without further input

Because the rules live in the conversation, you can change them on the fly by just telling Claude — no restart needed.

Troubleshooting

• If claude mcp list shows Needs authentication, re-run claude mcp login agentrux (safe to repeat)
• If the consent screen asks you to sign in, use the account that issued the connection URL
• If publish fails with a permission error, check in the Console that the Script's Grant covers the target Topic
• If pushes do not arrive: confirm the session was started with the channel flag, the confirmation prompt was accepted, and (in managed environments) channelsEnabled is set — then catch up with read_events