---
title: "Connect ACP Agents | AgentRQ Docs"
url: https://agentrq.com/docs/connect-acp-agent
description: "Use the open-source ACP Gateway to connect Gemini CLI and other ACP-compatible agents to your AgentRQ workspaces via MCP."
---

[Docs](https://agentrq.com/docs/) / Connect ACP Agents

ACP Setup Guide

# Connect ACP Agents

Use the open-source **@agentrq/acp-gateway** to connect Gemini CLI and other ACP-compatible agents to AgentRQ.

While Claude Code is natively supported, many other agents now support the **Agent Client Protocol (ACP)**. AgentRQ provides an open-source bridge (ACP Gateway) that allows these agents to use AgentRQ workspaces for human-in-the-loop task management.

How it works

ACP Agent (e.g. Gemini)

ACP Gateway

AgentRQ MCP Server

## 1 Find Your Agent

There is nothing to install. Every example here runs the Gateway through `npx @agentrq/acp-gateway@latest`, which fetches the current release each time — so you are never driving a version you installed months ago and forgot about.

```
# See which agents the ACP registry publishes
npx @agentrq/acp-gateway@latest --list-agents
```

`--list-agents` prints every agent in the [ACP registry](https://github.com/agentclientprotocol/registry) alongside how each one can run on this machine. The name in the first column is the **registry id** you pass to `--agent` everywhere below.

## 2 Configure .mcp.json

The Gateway reads your workspace configuration from `.mcp.json`. Place this file in your project root or any parent directory.

.mcp.json

```
{
  "mcpServers": {
    "agentrq": {
      "type": "http",
      "url": "https://WORKSPACE_ID.mcp.agentrq.com/mcp?token=TOKEN"
    }
  }
}
```

## 3 Start Your Agent

Run everything below from your workspace root — the directory holding `.mcp.json`. Log in once, then start the agent and leave it running; it picks up tasks as you assign them.

### Log In, Once

```
$ npx @agentrq/acp-gateway@latest --login --agent codex-acp
```

The first run also downloads the agent, so there is nothing to install by hand. Credentials stay with the agent — the Gateway never stores them.

### Start The Agent

```
$ npx @agentrq/acp-gateway@latest --agent codex-acp
```

Add `--max-concurrency 1` to keep the agent on one task at a time; it defaults to 1 and accepts more.

### Agents Without A Checksum

```
$ npx @agentrq/acp-gateway@latest --login --agent antigravity-acp --allow-unverified-agent
```

Registry binaries are checked against a published `sha256` before they run, and roughly half of them publish none. Rather than run something it cannot vouch for, the Gateway refuses and asks you to opt in explicitly. The flag is only needed while the binary is being installed — downloads are cached per agent, version and platform, so the runs after it can leave the flag off.

### Choosing A Model

```
$ npx @agentrq/acp-gateway@latest --list-models --agent antigravity-acp --allow-unverified-agent
$ npx @agentrq/acp-gateway@latest --model gemini-3.8-flash-high --agent antigravity-acp
$ npx @agentrq/acp-gateway@latest --agent antigravity-acp
```

Ask the agent what it supports, start it on one of those models, or omit `--model` and take the agent's default.

Not sure which registry id your agent uses? See the [ACP Agents Directory](https://agentrq.com/docs/agents) for Gemini CLI, Codex, Cursor, Cline, Hermes Agent, OpenClaw, and 50+ other ACP-compatible agents, or the [ACP support table](https://agentrq.com/blog/which-coding-agents-support-acp-agent-client-protocol) to see which agents support ACP natively and which need an adapter.

## 4 What the Gateway Bridges

Task Notifications

Forwarded from AgentRQ to your agent as ACP prompts.

Permission Requests

ACP agent requests permission → Gateway proxies to AgentRQ → verdict returned.

File Operations

Agents can read and write files relative to the current directory.

Tool Dispatch

Proxies ACP tool calls directly to AgentRQ MCP server tools.

## Open Source Gateway

The ACP Gateway is open-source and community-driven. You can inspect the code, contribute fixes, or build your own specialized bridge.

[View on GitHub](https://github.com/agentrq/acp-gateway)

Setup Complete?

Learn how to manage your workspace next.