MCP tools reference

All tools respond with a flat object: { success: boolean, ...fields } on success, or { success: false, error: string } on failure — there is no nested data field. agent_id is always included in parameters to track who called. session_id is injected automatically by the server from the RELAY_SESSION_ID environment variable — clients do not need to pass it (except where explicitly listed as a parameter below).

Server

get_server_info

Returns the active dashboard URL and server metadata. Call this during pre-flight to discover the auto-selected port.

Parameters:

{
  agent_id: string; // calling agent ID
}

Returns:

{
  success: true;
  dashboardUrl: string | null; // null if dashboard failed to bind
  dashboardAvailable: boolean;
  port: number | null;
  sessionId: string;
  instanceId: string | null;
}

---

start_session

Declares the active session ID for this relay run. Call once at the start of each /relay:relay invocation — before any other tools. Also broadcasts a session:started event to reset the live dashboard view.

Parameters:

{
  agent_id: string; // calling agent ID
  session_id: string; // session ID to activate (e.g. 2026-03-14-007)
}

Returns:

{
  success: true;
  session_id: string;
}

---

Messaging

send_message

Send a message between agents.

Parameters:

{
  agent_id: string;         // sending agent ID
  to?: string | null;       // receiving agent ID. null or omitted = broadcast
  content: string;          // message content
  thread_id?: string;       // thread ID (optional)
}

Returns:

{
  success: true;
  message_id: string;
}

---

get_messages

Fetch received messages (direct messages + broadcasts).

Parameters:

{
  agent_id: string; // agent ID to fetch messages for
}

Returns:

{
  success: true;
  messages: Array<{
    id: string;
    from_agent: string;
    to_agent: string | null;
    content: string;
    thread_id: string | null;
    created_at: number; // Unix epoch (seconds)
  }>;
}

---

Tasks

create_task

Create a new issue/task.

Parameters:

{
  agent_id: string;        // creating agent ID
  title: string;           // task title
  description?: string;    // detailed description with clear acceptance criteria
  assignee?: string;       // assigned agent ID (optional)
  priority: "critical" | "high" | "medium" | "low";
  depends_on?: string[];   // task IDs that must be done before this can start
  idempotency_key?: string; // if a task with this key exists, returns existing task_id (safe re-spawn)
  parent_task_id?: string; // parent task ID for derived tasks (max depth 1, max 3 siblings per parent)
  derived_reason?: string; // why this task was derived from its parent
}

Returns:

{
  success: true;
  task_id: string;
}

Returns { success: false, error: string } in these cases:

• Circuit breaker triggered (depth > 1 or > 3 siblings per parent)
• depends_on contains unknown task IDs (IDs must exist in the current session at creation time)
• parent_task_id does not exist in the current session

---

update_task

Change a task’s status or assignee.

Parameters:

{
  agent_id: string;    // calling agent ID
  task_id: string;     // task ID
  status?: "todo" | "in_progress" | "in_review" | "done";
  assignee?: string;   // new assignee (optional)
}

Returns:

{
  success: true;
}

---

claim_task

Atomically claim a task. Succeeds only if the task is in todo state and is assigned to (or unassigned from) the calling agent. Prevents race conditions where two agents try to pick up the same task simultaneously.

Parameters:

{
  agent_id: string; // agent ID claiming the task
  task_id: string; // task ID to claim
}

Returns:

{
  success: true;
  claimed: boolean;
  reason?: string; // reason if claimed: false
}

---

get_all_tasks

Returns all tasks in the session. When assignee is provided, only tasks assigned to that agent are returned.

Parameters:

{
  agent_id: string;   // calling agent ID
  assignee?: string;  // Optional assignee filter. When provided, only tasks assigned to this agent are returned.
}

Returns:

{
  success: true;
  tasks: Array<{
    id: string;
    title: string;
    status: string;
    assignee: string | null;
    priority: string;
  }>;
}

---

Artifacts

post_artifact

Share a deliverable (design spec, PR, report, etc.).

Parameters:

{
  agent_id: string;  // sharing agent ID
  name: string;      // artifact name (e.g. "login-fe-pr")
  type: "figma_spec" | "pr" | "report" | "analytics_plan" | "design" | "document";
  content: string;   // artifact content (text or JSON string)
  task_id?: string;  // associated task ID (optional)
}

Returns:

{
  success: true;
  artifact_id: string;
}

---

get_artifact

Retrieve an artifact by name.

Parameters:

{
  agent_id: string; // calling agent ID
  name: string; // artifact name
}

Returns:

{
  success: true;
  artifact: {
    id: string;
    name: string;
    type: string;
    content: string;
    created_by: string;
    task_id: string | null;
  }
}
// If not found: { success: false, artifact: null, error: "artifact not found" }

---

Review

request_review

Request a review for an artifact.

Parameters:

{
  agent_id: string; // requesting agent ID
  artifact_id: string; // artifact ID to review
  reviewer: string; // reviewer agent ID (e.g. fe2, be2)
}

Returns:

{
  success: true;
  review_id: string;
}

---

submit_review

Submit a review result. Returns permission denied if the calling agent is not the designated reviewer. Also returns an error if the review is no longer in pending state (prevents double-submit).

Parameters:

{
  agent_id: string;            // reviewer agent ID
  review_id: string;           // review ID
  status: "approved" | "changes_requested";
  comments?: string;           // review comments
}

Returns:

{
  success: true;
  review: {
    id: string;
    status: "approved" | "changes_requested";
    reviewer: string;
    comments: string | null;
  }
}

---

Memory

read_memory

Read an agent’s memory (or project memory).

Parameters:

{
  agent_id?: string; // if omitted, returns project.md only
}

Returns:

{
  success: true;
  content: string | null; // markdown text. null if the file does not exist
}

---

write_memory

Update a specific section of an agent’s memory. Adds the section if it doesn’t exist; replaces it if it does. Writes to project.md when agent_id is omitted.

Parameters:

{
  agent_id?: string; // agent ID. writes to project.md if omitted
  key: string;       // section key (e.g. "tech-stack", "conventions")
  content: string;   // new content
}

Returns:

{
  success: true;
}

---

append_memory

Append content with a datestamp to an agent’s personal memory file. agent_id is required — use save_session_summary for session-level retrospectives.

Parameters:

{
  agent_id: string; // agent ID (required)
  content: string; // content to append
}

Returns:

{
  success: true;
}

---

Sessions

save_session_summary

At session end, saves the session summary to .relay/sessions/{session_id}/summary.md. Session tasks and messages are stored in-memory and are not persisted to disk — pass a meaningful summary string as this is the durable record of what happened.

Parameters:

{
  agent_id: string; // calling agent ID (usually the coordinator)
  session_id: string; // session ID (YYYY-MM-DD-NNN-XXXX format)
  summary: string; // session summary text
}

Returns:

{
  success: true;
}

---

list_sessions

Retrieve past session IDs in reverse chronological order.

Parameters:

{
  agent_id: string; // calling agent ID
}

Returns:

{
  success: true;
  sessions: string[]; // session ID list (newest first)
}

---

get_session_summary

Retrieve the summary for a specific session.

Parameters:

{
  agent_id: string; // calling agent ID
  session_id: string; // session ID
}

Returns:

{
  success: true;
  summary: string; // contents of summary.md
}

---

save_orchestrator_state

Save the orchestrator’s event loop state. Stored in-memory, scoped to the current session. Use this to persist state across context compaction — call get_orchestrator_state on the next spawn to resume.

Parameters:

{
  agent_id: string; // calling agent ID (typically the orchestrator)
  state: string; // JSON-stringified event loop state
  // Shape: { base_agents, dormant_agents, done_agents, last_seen_msg_id, agent_last_seen, iteration, spawned_reviewers }
}

Returns:

{
  success: true;
}

---

get_orchestrator_state

Retrieve the orchestrator’s previously saved event loop state for the current session. Returns { success: true, state: null } if no state has been saved yet.

Parameters:

{
  agent_id: string; // calling agent ID (typically the orchestrator)
}

Returns:

{
  success: true;
  state: string | null; // JSON-stringified state, or null if not set
}

---

Agents

list_agents

Retrieve the list of agents for the given session (loaded from .relay/session-agents-{session_id}.yml). Returns { success: false, error: "..." } when a session_id is provided but the corresponding file does not exist.

Parameters:

{
  agent_id: string;      // calling agent ID
  session_id?: string;   // session ID — when provided, loads the session-specific team file
                         // written by /relay:relay Team Composition step
}

Returns:

{
  success: true;
  agents: Array<{
    id: string;
    name: string;
    emoji: string;
    description: string;
    tools: string[];
    systemPrompt: string;
  }>;
}

---

list_pool_agents

Retrieve all available pool agents for team selection. Returns metadata only — systemPrompt is intentionally omitted. Used during pre-flight before a session is started.

Parameters:

{
  agent_id: string; // calling agent ID
}

Returns:

{
  success: true;
  agents: Array<{
    id: string;
    name: string;
    emoji: string;
    description: string;
    tags: string[] | undefined;
    tools: string[];
  }>;
}

---

Visibility

broadcast_thinking

Push an agent’s current intent to the dashboard as an agent:thinking WebSocket event. Fire-and-forget — does not write to the database. Add this to your agent’s tools list and call it before each significant operation.

Parameters:

{
  agent_id: string; // calling agent ID
  content: string; // what the agent is about to do or thinking about
}

Returns:

{
  success: true;
}

Tip

Call broadcast_thinking before each significant operation to make the agent’s intent visible in the dashboard Thoughts panel.