Reference
Workspace MCP Reference
AgentRQ exposes 6 MCP tools to Claude Code within a specific workspace. All tools are available
after connecting via .mcp.json.
All 6 Tools
createTask
Create a task for the human or agent to handle
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
title |
string | required | Short task title shown in the dashboard |
body |
string | required | Full task description — include all context the human needs |
assignee |
"human" | "agent" | optional | Who the task is assigned to. Default: "agent" |
attachments |
Attachment[] | optional | Array of file attachments (see Attachment type below) |
Returns
{ task_id: string } — the ID of the
newly created task
Example
Claude
Code
const result = await createTask({
title: "Review: DB migration for user_sessions table",
body: `## What I'm about to do
Add a new \`user_sessions\` table to store auth tokens.
## Migration SQL
\`\`\`sql
CREATE TABLE user_sessions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id INTEGER REFERENCES users(id),
token_hash VARCHAR(64) NOT NULL,
created_at TIMESTAMPTZ DEFAULT NOW(),
expires_at TIMESTAMPTZ NOT NULL
);
CREATE INDEX ON user_sessions(expires_at);
\`\`\`
## Approve to proceed?`,
assignee: "human"
});
console.log(result.task_id); // "0ZRgCquBZ7R"updateTaskStatus
Transition a task to a new status
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
task_id |
string | required | ID of the task to update |
status |
"ongoing" | "completed" | "rejected" | "notstarted" | required | The new status to transition to |
Best Practice
Always call
updateTaskStatus("ongoing") as the
first thing when you start working on a task. This
signals to the human that the agent has seen their request.
Example
Claude
Code
// Received task — immediately mark as ongoing
await updateTaskStatus({
task_id: "0ZRgCquBZ7R",
status: "ongoing"
});
// ... do work ...
// Done — mark completed
await updateTaskStatus({
task_id: "0ZRgCquBZ7R",
status: "completed"
});reply
Send a message in a task thread
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
chat_id |
string | required | The chat ID from the channel message (same as task_id) |
text |
string | required | The message text to send |
attachments |
Attachment[] | optional | Files to attach to the reply |
Example
Claude Code
— sending progress update
await reply({
chat_id: "0ZRgCquBZ7R",
text: "Migration complete. 14,322 rows deleted. Here's the query plan:",
attachments: [{
id: "att_plan_001",
filename: "query-plan.txt",
mimeType: "text/plain",
data: btoa(queryPlanText) // base64 encoded
}]
});getWorkspace
Fetch workspace metadata and context
Parameters
None — takes no parameters. Returns info about the workspace the MCP token belongs to.
Returns
Workspace name, ID, owner, and any custom mission/context set in settings.
When to Call
Call at the start of every session to load workspace
context and confirm connectivity. Include it as an instruction in your CLAUDE.md.
Example
Claude
Code
const workspace = await getWorkspace();
// Returns:
{
id: "0ZPO4WBMZIP",
name: "my-saas-backend",
owner: "[email protected]",
mission: "Build the v2 API. Ask before any DB changes or deploys."
}getTask
Fetch the next "not started" task, or a specific task — optionally with its conversation history
With no
taskId, getTask
dequeues the oldest "not started" task assigned to the agent (and associates it with the
current session). Pass a taskId to fetch that specific
task instead. Set includeConversation to append the
task's chat history.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
taskId |
string | optional | A specific task to fetch. Omit to dequeue the next "not started" task. |
includeConversation |
boolean | optional | When true, appends the task's chat history. Default: false |
cursor |
string | null | optional | Pagination cursor for conversation messages. null = start from beginning |
limit |
integer | optional | Max conversation messages to return. Default: 20, max: 100 |
Returns
A single Task object (ID, title, body, attachments) — or null if no task is available.
When
includeConversation is true, the response also
carries the chat history as { messages, total, cursor }.
Example
Claude
Code
// Dequeue the next "not started" task
const task = await getTask();
if (task) {
console.log(`Found next task: ${task.title}`);
await updateTaskStatus({ task_id: task.id, status: "ongoing" });
} else {
console.log("No pending tasks.");
}
// Fetch a specific task with its conversation history
const result = await getTask({
taskId: "0ZRgCquBZ7R",
includeConversation: true,
cursor: null,
limit: 50
});
// result.messages → { messages: [...], total, cursor }downloadAttachment
Fetch a file attached by the human in the dashboard
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
attachment_id |
string | required | The attachment ID from the channel message |
Returns
{ data: string, filename: string, mimeType: string }
— base64-encoded file content
Example
Claude Code
— human sent a file
// Channel message contains attachment ID
// <channel ...> [attachment: att_abc123 — design.png] </channel>
const file = await downloadAttachment({
attachment_id: "att_abc123"
});
// file.data is base64 — decode to use
const content = Buffer.from(file.data, "base64");
console.log(file.filename); // "design.png"
console.log(file.mimeType); // "image/png"Attachment Type
Used in createTask and reply
when sending files from Claude to the human:
| Field | Type | Description |
|---|---|---|
id |
string | Unique ID for this attachment (any string) |
filename |
string | Display filename (e.g., "schema.sql") |
mimeType |
string | MIME type (e.g., "text/plain", "image/png") |
data |
string | Base64-encoded file content |