Workspace MCP Reference

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 created with id=0ZRgCquBZ7R"

// Received task — immediately mark as ongoing
await updateTaskStatus({
  taskId: "0ZRgCquBZ7R",
  status: "ongoing"
});

// ... do work ...

// Done — mark completed
await updateTaskStatus({
  taskId: "0ZRgCquBZ7R",
  status: "completed"
});

await reply({
  chatId: "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
  }]
});

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."
}

// Dequeue the next "not started" task
const task = await getTask();
if (task) {
  console.log(`Found next task: ${task.title}`);
  await updateTaskStatus({ taskId: 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 }

// Channel message contains attachment ID
// <channel ...> [attachment: att_abc123 — design.png] </channel>

const data = await downloadAttachment({
  attachmentId: "att_abc123",
  taskId:       "0ZRgCquBZ7R"
});

// the response is the content itself — decode to use
const content = Buffer.from(data, "base64");

// The task said:
// [On completion: call publishEvent("tests_passed", "<payload>")]

await updateTaskStatus({ taskId: "0ZRgCquBZ7R", status: "completed" });

await publishEvent({
  name:    "tests_passed",       // copied from the instruction
  taskId:  "0ZRgCquBZ7R",        // copied from the instruction
  payload: "482 passed, 0 failed on build 2.3.1.",
  faq: [
    { q: "Any flakes?", a: "One retry in the billing suite, passed on rerun." }
  ]
});

// Start with the index.
const index = await loadMemory();
// # What this workspace remembers
// - [How we deploy](memory://deploys.md) — the two gates that are not automated.
// - [The flaky tests](memory://flaky-tests.md) — which failures are real.

// Then load only what this task needs.
const deploys = await loadMemory({ name: "deploys.md" });

// Write the detail into its own memory.
await saveMemory({
  name: "deploys.md",
  content: [
    "# How we deploy",
    "",
    "Production needs a human to approve the release.",
    "Drain settlement retries first: a release mid-drain",
    "leaves duplicate charges to reconcile by hand."
  ].join("\n")
});

// Then link it from the index, which agents read first.
await saveMemory({
  content: [
    "# What this workspace remembers",
    "",
    "- [How we deploy](memory://deploys.md) — the manual gate."
  ].join("\n")
});
// Returns: Saved "memory.md" (98 bytes).

// The flaky-tests memory no longer applies; remove it.
await deleteMemory({ name: "flaky-tests.md" });
// Returns: Deleted "flaky-tests.md".

// Retrying a delete that already happened is not an error.
await deleteMemory({ name: "flaky-tests.md" });
// Returns: No memory was stored under "flaky-tests.md"; nothing to delete.

const answer = await elicit({
  taskId:  "0ZRgCquBZ7R",
  mode:    "form",
  message: "Which environment should I deploy to?",
  requestedSchema: {
    type: "object",
    properties: {
      environment: { type: "string", enum: ["staging", "production"] },
      runMigrations: { type: "boolean" }
    },
    required: ["environment"]
  }
});

// A timeout is a "cancel", not an error — treat it as an answer.
if (answer.action !== "accept") return;

deploy(answer.content.environment, answer.content.runMigrations);