---
title: "Fix a Disconnected AgentRQ MCP in Claude Code | AgentRQ Guidelines"
url: https://agentrq.com/guidelines/connect-agents/reconnect-disconnected-agentrq-mcp-in-claude-code
description: "Workspace offline while Claude Code still runs? Open its terminal in AgentRQ, type /mcp, pick agentrq-workspace and Reconnect. Step by step, with screenshots."
---

![](https://agentrq.com/assets/agent-icons/claude-agent.png) Checked November 16, 2026 | [All Connect Agents guides](https://agentrq.com/guidelines/connect-agents/)

# Fix a Disconnected AgentRQ MCP in Claude Code

When the workspace's dot turns red but Claude Code is still running on your machine, Claude Code has lost its connection to the workspace's MCP server, `agentrq-workspace`. You can fix it from the browser in under a minute: click the **terminal icon** in the workspace toolbar, type `/mcp` in Claude Code's terminal, pick **agentrq-workspace**, and choose **Reconnect**. The dot turns green again, and Claude Code keeps its conversation, so there is nothing to restart.

This page is one of our [connect agents guidelines](https://agentrq.com/guidelines/connect-agents/). It follows on from [Connect Claude Code with Machines](https://agentrq.com/guidelines/connect-agents/claude-code-and-machines), and it was checked against AgentRQ and Claude Code 2.1.325 on November 16, 2026. Every screenshot below comes from a real run, where the connection was broken by taking the AgentRQ server away for two minutes.

## Why the MCP Server Disconnects

Claude Code gets its tasks over the workspace's MCP server. If that connection drops for long enough, Claude Code stops retrying and marks the server as **failed**. Common causes:

- → The machine slept, or its network changed or dropped for a while.
- → The AgentRQ server was restarted or briefly unreachable.
- → A VPN, proxy or firewall closed the long-running connection.

The Claude Code process itself keeps running. The machine's daemon reconnects on its own, so the session and its terminal stay available in AgentRQ. Only Claude Code's own MCP connection stays down, and while it is down no task reaches the agent: new tasks wait in **Not Started**.

## Step by Step: Reconnect From the AgentRQ Terminal

**1. Spot the red dot** next to the workspace's name. The workspace is offline: no agent is connected to its MCP server.

**2. Click the terminal icon** in the toolbar. It stays lit while Claude Code is running on the machine, even with the MCP server disconnected, and opens Claude Code's live terminal.

![Steps 1 and 2: the storefront-api workspace with a red dot next to its name, and an arrow pointing at the green Agent terminal icon in the toolbar](https://agentrq.com/assets/guidelines/connect-reconnect-1-offline-terminal-icon.png)

Do not click **Start an agent** here. Claude Code is still running for this workspace, and reconnecting it keeps its conversation.

**3. Click the prompt** in the terminal. The terminal in AgentRQ is the real one, so what you type goes to Claude Code on the machine.

![Step 3: Claude Code's terminal in AgentRQ, with an arrow pointing at the empty prompt](https://agentrq.com/assets/guidelines/connect-reconnect-2-click-prompt.png)

**4. Type /mcp and press Enter.** The command list shows `/mcp` as **Manage MCP servers**.

![Step 4: /mcp typed at the prompt, with the Manage MCP servers suggestion highlighted](https://agentrq.com/assets/guidelines/connect-reconnect-3-type-mcp.png)

**5. Pick agentrq-workspace and press Enter.** It is listed under **Project MCPs**, with a red cross because it failed. Use the arrow keys if it is not already selected.

![Step 5: the Manage MCP servers list, with the failed agentrq-workspace server under Project MCPs highlighted](https://agentrq.com/assets/guidelines/connect-reconnect-4-failed-server.png)

**6. Check the status.** The server page says **failed**, and the **Issue** line says why. Here it is `ECONNREFUSED`: Claude Code could not reach the server when it last tried.

**7. Pick Reconnect and press Enter.** Press the Down arrow once to move from **Authenticate** to **Reconnect**. You do not need **Authenticate**: the workspace token is already in the URL.

![Steps 6 and 7: the agentrq-workspace MCP Server page with Status failed highlighted, and 2. Reconnect selected and highlighted](https://agentrq.com/assets/guidelines/connect-reconnect-5-reconnect.png)

**8. Check the result.** Claude Code prints **Reconnected to agentrq-workspace.** and returns to its prompt.

![Step 8: the terminal showing](https://agentrq.com/assets/guidelines/connect-reconnect-6-reconnected.png)

**9. Go back to the workspace.** The dot next to its name is green again, and tasks reach Claude Code as before. A task that waited in **Not Started** while it was down can now be picked up.

![Step 9: the storefront-api workspace with a green dot next to its name, highlighted, and the message that the agent is connected and ready](https://agentrq.com/assets/guidelines/connect-reconnect-7-connected.png)

## If Reconnect Does Not Work

- → **The terminal icon is missing.** Claude Code is no longer running on the machine, so there is nothing to reconnect. Click **Start an agent** to start it again, as in [Connect Claude Code with Machines](https://agentrq.com/guidelines/connect-agents/claude-code-and-machines).
- → **Reconnect fails with the same issue.** Claude Code still cannot reach AgentRQ from that machine. Check the machine's network, then check that it shows as online on the **Machines** page, and try again.
- → **The issue mentions 401, 403 or authentication.** The token in the folder's `.mcp.json` no longer works, which happens after you [reset the workspace ID](https://agentrq.com/guidelines/security/compromised-mcp-json). Reconnecting cannot fix that: put the new `.mcp.json` in the folder, then stop Claude Code with **Stop** on its terminal page and start it again.
- → **Nothing helps.** Click **Stop** on the terminal page, then **Start an agent**. Claude Code starts fresh in the same folder, without the old conversation.

## Running Claude Code From Your Own Terminal?

The fix is the same. If you started Claude Code yourself with the workspace's `.mcp.json`, as in the last section of [Connect Claude Code with Machines](https://agentrq.com/guidelines/connect-agents/claude-code-and-machines), type `/mcp` in that terminal, pick **agentrq-workspace**, and choose **Reconnect**. Without the machine's daemon there is no terminal icon in AgentRQ, so you do it at the machine.

## FAQ

### Does reconnecting lose Claude Code's conversation?

No. Reconnect only reopens the connection to the MCP server. The Claude Code session, its context and its model stay as they were. Stopping and starting Claude Code is what starts a new conversation.

### Why does the workspace show offline while Claude Code is running?

The dot shows whether an agent is connected to the workspace's MCP server, not whether a process runs on the machine. Claude Code can be running with its MCP connection marked failed, and then the workspace is offline until you reconnect.

### Will Claude Code reconnect on its own?

It retries for a while after the connection drops. If the server comes back in time, it reconnects by itself. After a longer outage it gives up and marks the server as failed, and from then on it waits for you to choose **Reconnect** in `/mcp`.

### Can I use Authenticate instead?

No. **Authenticate** is for MCP servers that sign in with OAuth. The AgentRQ workspace server is authorised by the token in its URL, so **Reconnect** is the option to pick.
