agentrq

Shows active maintenance signals

AgentRQ is designed for seamless integration as a Claude Channel. This allows your AI agents to see tasks assigned to them and respond directly within your Claude session.

Each workspace has its own MCP URL and token (visible in the workspace setup modal). In production, these follow the pattern https://WORKSPACE_ID.mcp.agentrq.com/.

Step 1 — .mcp.json

Create a .mcp.json file in your local project directory (the leading dot is required). Each project gets its own file so Claude instances stay isolated per workspace. Replace YOUR_MCP_URL below with the full URL shown in the setup modal (e.g. https://WORKSPACE_ID.mcp.agentrq.com/?token=TOKEN).

{
  "mcpServers": {
    "agentrq-WORKSPACE_ID": {
      "type": "http",
      "url": "YOUR_MCP_URL"
    }
  }
}

Step 2 — .claude/settings.local.json

Add a .claude/settings.local.json file in the same project directory to pre-approve the AgentRQ tools and avoid permission prompts on every action:

{
  "permissions": {
    "allow": [
      "mcp__agentrq-WORKSPACE_ID__updateTaskStatus",
      "mcp__agentrq-WORKSPACE_ID__getWorkspace",
      "mcp__agentrq-WORKSPACE_ID__reply",
      "mcp__agentrq-WORKSPACE_ID__createTask",
      "mcp__agentrq-WORKSPACE_ID__downloadAttachment",
      "mcp__agentrq-WORKSPACE_ID__getTask"
    ]
  },
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": ["agentrq-WORKSPACE_ID"]
}

Step 3 — Start Claude

Once both files are in place, launch Claude Code from that project directory:

claude --dangerously-load-development-channels server:agentrq-WORKSPACE_ID

Tip: The workspace ID, full MCP URL (with token), and ready-to-paste config snippets are all available in the Setup modal inside each AgentRQ workspace.

Available MCP Tools

When connected, the AI agent has access to:

• createTask: Assign a task to the human user (supports optional cron_schedule for recurring tasks).
• updateTaskStatus: Move tasks through notstarted, ongoing, blocked, and completed.
• reply: Send messages back to the AgentRQ dashboard in real-time.
• getWorkspace: Fetch the workspace name, mission description, and task statistics.
• getTask: Fetch a task — with no taskId it dequeues the next "not started" task assigned to the agent; with a taskId it returns that task. Pass includeConversation: true to also include the chat history (cursor-based pagination).
• downloadAttachment: Retrieve an attachment by its ID.
• Real-time Notifications: Agents receive notifications via the notifications/claude/channel protocol whenever a human interacts with their tasks.

While Claude Code has native support for claude/notifications, other agents like Gemini CLI require a bridge to receive real-time task notifications from AgentRQ. The @agentrq/acp-gateway bridges the Agent Client Protocol (ACP) with MCP to enable this.

Installation

npm install -g @agentrq/acp-gateway

Usage

1. Ensure you have a .mcp.json in your project root.
2. Run the gateway followed by your agent's ACP command:

# Using Gemini CLI
acp-gateway -- gemini --acp

The gateway will automatically:

• Connect to your AgentRQ workspace via the URL in .mcp.json.
• Spawn the agent subprocess and bridge standard I/O.
• Forward task assignments, messages, and permission requests in real-time.

Usage

Run codex-gateway from your agentrq workspace root (the directory containing .mcp.json):

# Default: runs `codex app-server`
codex-gateway

# Custom codex command
codex-gateway -- codex app-server

Communication & Files

• replyToTask: Post a message to a task's chat thread.
• respondToTask: Submit an allow/deny verdict for a permission request.
• getAttachment: Retrieve data as base64 and metadata for a specific attachment.

Connecting to Supervisor (Claude Code)

Since the Supervisor uses OAuth2, you can connect it using the following configuration in your ~/.mcp.json:

{
  "mcpServers": {
    "agentrq": {
      "type": "http",
      "url": "https://mcp.agentrq.com/mcp"
    }
  }
}

When you first run Claude with this server, it will provide a link to authenticate via your browser.