--- title: "Connect Claude Code | AgentRQ Docs" url: https://agentrq.com/docs/connect-claude-code description: "Configure .mcp.json, generate your MCP token, and add the AgentRQ notification channel to your CLAUDE.md. Full setup guide." --- [Docs](https://agentrq.com/docs/) / Connect Claude Code Setup Guide # Connect Claude Code Full setup guide for wiring AgentRQ into Claude Code — from `.mcp.json` configuration to CLAUDE.md instructions and permission handling. Prerequisites - Claude Code installed — see [Install Claude Code](https://agentrq.com/docs/connect-claude-code#install-claude-code) below - AgentRQ account at [app.agentrq.com](https://app.agentrq.com/login?utm_source=docs-connect-claude-code&utm_term=signup) - A workspace created with an MCP token generated ## Install Claude Code Already installed? Skip ahead — run `claude --version` to check first. Native install (recommended) macOS, Linux, WSL ``` curl -fsSL https://claude.ai/install.sh | bash ``` Windows — PowerShell ``` irm https://claude.ai/install.ps1 | iex ``` Windows — CMD ``` curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd ``` Not sure which Windows shell you're in? Your prompt shows `PS C:\` in PowerShell and just `C:\` in CMD. Native installs update themselves automatically in the background; on native Windows, [Git for Windows](https://git-scm.com/downloads/win) is recommended so Claude Code can use its Bash tool (not needed under WSL). Alternative install methods macOS — Homebrew `brew install --cask claude-code` Does not auto-update — run `brew upgrade claude-code` periodically. Windows — WinGet `winget install Anthropic.ClaudeCode` Does not auto-update — run `winget upgrade Anthropic.ClaudeCode` periodically. Debian, Fedora, RHEL, and Alpine can also install via apt, dnf, or apk — see the [official Linux package manager guide](https://code.claude.com/docs/en/setup#install-with-linux-package-managers). Confirm the install worked: `claude --version` should print a version number followed by `(Claude Code)`. ## 1 Configure .mcp.json Create or update `.mcp.json` in your project root. Claude Code auto-loads this file when you start a session. .mcp.json project root ``` { "mcpServers": { "agentrq": { "type": "http", "url": "https://WORKSPACE_ID.mcp.agentrq.com/mcp?token=MCP_TOKEN" } } } ``` WORKSPACE_ID Found in your workspace URL or workspace settings page. Looks like: `0ZPO4WBMZIP` MCP_TOKEN Available in workspace settings. Valid for 1 year. Security: Add `.mcp.json` to your `.gitignore` if your token is embedded. Alternatively, use environment variable substitution in `.mcp.json`. ## 2 Global vs Project Config You can add AgentRQ at the project level (per project root) or globally (all Claude Code sessions). Project-Level Recommended Place `.mcp.json` in your project root. Only active when you `cd` into that project and run `claude`. ./my-project/.mcp.json Global Place in `~/.claude/mcp.json`. AgentRQ tools available in every Claude Code session, every project. ~/.claude/mcp.json ## 3 Add CLAUDE.md Instructions Tell Claude when and how to use AgentRQ tools by adding instructions to your `CLAUDE.md`. This is the most important step — it shapes Claude's behavior throughout your session. CLAUDE.md (example) ``` ## Human-in-the-Loop (AgentRQ) # At the start of every session: Call `workspace` with action `get` to load context about this workspace. # When you need human input, approval, or a decision: Use `task` with action `create` and assignee `human`. Include: - A clear title - Full context in the body (what you've done, what you need) - Any relevant file snippets as attachments Then wait for the human's response via the notification channel. Do NOT proceed past a blocking decision without human approval. # When you receive a reply: Read the reply, set the task `completed` (`task` action `updateStatus`), then continue. # When asked to make irreversible changes (DB, deploys, deletes): Always ask via `task` action `create` before executing. ``` Adapt this template to your workflow. The key is being explicit about when Claude should pause and ask vs. when it can proceed autonomously. If an existing `CLAUDE.md` names the older tools, such as `createTask` or `getWorkspace`, update it to the action form. The server still answers those names for clients that call them directly, but no longer lists them, so Claude does not see them. See the [MCP tools reference](https://agentrq.com/docs/mcp-tools#old-names). ## 4 The Notification Channel When you reply to a task in the AgentRQ dashboard, your response is delivered to Claude Code as a **notification channel message** — Claude's native push mechanism. The message looks like this in Claude's context: Claude Code context — incoming message ``` [Response to task 0ZRgCquBZ7R] Approved — but use a UUID primary key instead of auto-increment. Please add an index on expires_at too. ``` Claude reads this channel message, processes your reply, and continues — all within the same session. No interruption, no re-prompting. Permission Requests Claude Code can also send permission requests for sensitive operations. These show up as special task types in your dashboard with Allow / Deny / Allow All buttons. Example permission request Claude is requesting permission to run: `rm -rf dist/` ## 5 Verify the Connection Start Claude Code and run this quick test: Test prompt ``` > Call workspace get and tell me what workspace you're connected to. Then create a test task called "Connection test" with body "Hello from Claude". Claude: I called workspace get — connected to workspace "my-api-project" (ID: 0ZPO4WBMZIP). Creating test task now... Task created ✓ (ID: 0ZRgXXXXXXX). You should see it in your dashboard. ``` Check your AgentRQ dashboard — the task should appear instantly. Reply to it, and Claude will receive your message via the notification channel. ## Troubleshooting AgentRQ tools not appearing Verify `.mcp.json` is valid JSON (no trailing commas). Restart Claude Code. Check the URL contains both WORKSPACE_ID and token query param. 401 / Unauthorized error Your MCP token may have expired (1-year validity period) or been revoked. Check workspace settings. Notifications not arriving in Claude Claude Code must be actively running (not paused at input). The SSE connection drops when Claude is waiting for user input. Resume Claude to receive pending messages. Tasks created but dashboard empty Check you're viewing the correct workspace in the dashboard. The WORKSPACE_ID in `.mcp.json` must match the workspace you're viewing. Connection working? Learn the full task lifecycle next.