MCP 도구 레퍼런스

모든 도구는 성공 시 { success: boolean, ...fields } 형태의 flat 객체를, 실패 시 { success: false, error: string }을 반환합니다. 중첩된 data 필드는 없습니다. agent_id는 호출자 추적을 위해 항상 포함합니다. session_id는 서버가 RELAY_SESSION_ID 환경 변수에서 자동 주입하므로 클라이언트가 직접 전달할 필요 없습니다 (아래에서 파라미터로 명시된 경우는 제외).

서버

get_server_info

활성 대시보드 URL과 서버 메타데이터를 반환합니다. 사전 점검(pre-flight) 단계에서 자동 선택된 포트를 확인할 때 사용합니다.

파라미터:

{
  agent_id: string; // 호출 에이전트 ID
}

반환값:

{
  success: true;
  dashboardUrl: string | null; // 대시보드 바인딩 실패 시 null
  dashboardAvailable: boolean;
  port: number | null;
  sessionId: string;
  instanceId: string | null;
}

---

start_session

현재 relay 실행의 활성 세션 ID를 선언합니다. /relay:relay 호출 시작 시 다른 도구보다 먼저 한 번 호출하세요. 라이브 대시보드 뷰를 초기화하는 session:started 이벤트도 함께 브로드캐스트합니다.

파라미터:

{
  agent_id: string; // 호출 에이전트 ID
  session_id: string; // 활성화할 세션 ID (예: 2026-03-14-007)
}

반환값:

{
  success: true;
  session_id: string;
}

---

메시징

send_message

에이전트 간 메시지를 보냅니다.

파라미터:

{
  agent_id: string;         // 발신 에이전트 ID
  to?: string | null;       // 수신 에이전트 ID. null 또는 생략 시 전체 브로드캐스트
  content: string;          // 메시지 내용
  thread_id?: string;       // 스레드 ID (선택)
}

반환값:

{
  success: true;
  message_id: string;
}

---

get_messages

수신 메시지를 가져옵니다 (다이렉트 메시지 + 브로드캐스트).

파라미터:

{
  agent_id: string; // 메시지를 가져올 에이전트 ID
}

반환값:

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

---

태스크

create_task

새 태스크를 만듭니다.

파라미터:

{
  agent_id: string;        // 생성 에이전트 ID
  title: string;           // 태스크 제목
  description?: string;    // 명확한 완료 조건을 포함한 상세 설명
  assignee?: string;       // 담당 에이전트 ID (선택)
  priority: "critical" | "high" | "medium" | "low";
  depends_on?: string[];   // 선행 태스크 ID 목록 (이 태스크 시작 전 완료 필요)
  idempotency_key?: string; // 같은 키의 태스크가 이미 있으면 기존 task_id를 반환 (재실행 안전)
  parent_task_id?: string; // 파생 태스크의 부모 태스크 ID (최대 깊이 1, 부모당 최대 3개)
  derived_reason?: string; // 부모에서 파생된 이유
}

반환값:

{
  success: true;
  task_id: string;
}

다음 경우 { success: false, error: string }을 반환합니다:

• 서킷 브레이커 발동 (깊이 > 1 또는 부모당 형제 > 3개)
• depends_on에 존재하지 않는 태스크 ID 포함 (현재 세션에 있어야 함)
• parent_task_id가 현재 세션에 없음

---

update_task

태스크의 상태나 담당자를 변경합니다.

파라미터:

{
  agent_id: string;    // 호출 에이전트 ID
  task_id: string;     // 태스크 ID
  status?: "todo" | "in_progress" | "in_review" | "done";
  assignee?: string;   // 새 담당자 (선택)
}

반환값:

{
  success: true;
}

---

claim_task

태스크를 원자적으로 클레임합니다. todo 상태이고, 호출 에이전트에게 배정되었거나 미배정인 태스크만 클레임할 수 있습니다. 두 에이전트가 같은 태스크를 동시에 잡으려는 레이스 컨디션을 방지합니다.

파라미터:

{
  agent_id: string; // 클레임하는 에이전트 ID
  task_id: string; // 클레임할 태스크 ID
}

반환값:

{
  success: true;
  claimed: boolean;
  reason?: string; // claimed: false인 경우 사유
}

---

get_all_tasks

세션의 모든 태스크를 반환합니다. assignee를 지정하면 해당 에이전트의 태스크만 반환합니다.

파라미터:

{
  agent_id: string;   // 호출 에이전트 ID
  assignee?: string;  // 담당자 필터 (선택). 지정 시 해당 에이전트의 태스크만 반환
}

반환값:

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

---

아티팩트

post_artifact

산출물(디자인 스펙, PR, 리포트 등)을 공유합니다.

파라미터:

{
  agent_id: string;  // 공유 에이전트 ID
  name: string;      // 아티팩트 이름 (예: "login-fe-pr")
  type: "figma_spec" | "pr" | "report" | "analytics_plan" | "design" | "document";
  content: string;   // 내용 (텍스트 또는 JSON 문자열)
  task_id?: string;  // 연관 태스크 ID (선택)
}

반환값:

{
  success: true;
  artifact_id: string;
}

---

get_artifact

이름으로 아티팩트를 가져옵니다.

파라미터:

{
  agent_id: string; // 호출 에이전트 ID
  name: string; // 아티팩트 이름
}

반환값:

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

---

리뷰

request_review

아티팩트의 리뷰를 요청합니다.

파라미터:

{
  agent_id: string; // 요청 에이전트 ID
  artifact_id: string; // 리뷰 대상 아티팩트 ID
  reviewer: string; // 리뷰어 에이전트 ID (예: fe2, be2)
}

반환값:

{
  success: true;
  review_id: string;
}

---

submit_review

리뷰 결과를 제출합니다. 호출 에이전트가 지정된 리뷰어가 아니면 권한 오류를 반환합니다. 리뷰가 이미 pending이 아닌 경우에도 오류를 반환합니다 (중복 제출 방지).

파라미터:

{
  agent_id: string;            // 리뷰어 에이전트 ID
  review_id: string;           // 리뷰 ID
  status: "approved" | "changes_requested";
  comments?: string;           // 리뷰 코멘트
}

반환값:

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

---

메모리

read_memory

에이전트 메모리(또는 프로젝트 메모리)를 읽습니다.

파라미터:

{
  agent_id?: string; // 생략하면 project.md만 반환
}

반환값:

{
  success: true;
  content: string | null; // 마크다운 텍스트. 파일이 없으면 null
}

---

write_memory

에이전트 메모리의 특정 섹션을 갱신합니다. 섹션이 없으면 추가하고, 있으면 교체합니다. agent_id를 생략하면 project.md에 씁니다.

파라미터:

{
  agent_id?: string; // 에이전트 ID. 생략 시 project.md에 기록
  key: string;       // 섹션 키 (예: "tech-stack", "conventions")
  content: string;   // 새 내용
}

반환값:

{
  success: true;
}

---

append_memory

에이전트 개인 메모리 파일에 날짜 스탬프와 함께 내용을 덧붙입니다. agent_id는 필수입니다. 세션 회고에는 save_session_summary를 사용하세요.

파라미터:

{
  agent_id: string; // 에이전트 ID (필수)
  content: string; // 추가할 내용
}

반환값:

{
  success: true;
}

---

세션

save_session_summary

세션 종료 시 요약을 .relay/sessions/{session_id}/summary.md에 저장합니다. 태스크와 메시지는 in-memory에만 있고 디스크에 남지 않으므로, 의미 있는 요약을 남겨야 합니다. 이것이 세션의 유일한 영구 기록입니다.

파라미터:

{
  agent_id: string; // 호출 에이전트 ID (보통 코디네이터)
  session_id: string; // 세션 ID (YYYY-MM-DD-NNN-XXXX 형식)
  summary: string; // 세션 요약 텍스트
}

반환값:

{
  success: true;
}

---

list_sessions

과거 세션 ID를 최신순으로 가져옵니다.

파라미터:

{
  agent_id: string; // 호출 에이전트 ID
}

반환값:

{
  success: true;
  sessions: string[]; // 세션 ID 목록 (최신순)
}

---

get_session_summary

특정 세션의 요약을 가져옵니다.

파라미터:

{
  agent_id: string; // 호출 에이전트 ID
  session_id: string; // 세션 ID
}

반환값:

{
  success: true;
  summary: string; // summary.md 내용
}

---

save_orchestrator_state

오케스트레이터의 이벤트 루프 상태를 저장합니다. 현재 세션 범위의 in-memory 저장입니다. 컨텍스트 압축 후에도 상태를 이어가기 위해 사용합니다. 다음 실행 시 get_orchestrator_state로 복원하세요.

파라미터:

{
  agent_id: string; // 호출 에이전트 ID (보통 오케스트레이터)
  state: string; // JSON 문자열로 직렬화된 이벤트 루프 상태
  // 형태: { base_agents, dormant_agents, done_agents, last_seen_msg_id, agent_last_seen, iteration, spawned_reviewers }
}

반환값:

{
  success: true;
}

---

get_orchestrator_state

이전에 저장한 오케스트레이터 이벤트 루프 상태를 가져옵니다. 저장된 상태가 없으면 { success: true, state: null }을 반환합니다.

파라미터:

{
  agent_id: string; // 호출 에이전트 ID (보통 오케스트레이터)
}

반환값:

{
  success: true;
  state: string | null; // JSON 문자열 상태, 또는 미설정 시 null
}

---

에이전트

list_agents

세션의 에이전트 목록을 가져옵니다 (.relay/session-agents-{session_id}.yml에서 로드). session_id를 지정했는데 해당 파일이 없으면 { success: false, error: "..." }을 반환합니다.

파라미터:

{
  agent_id: string;      // 호출 에이전트 ID
  session_id?: string;   // 세션 ID — 지정 시 /relay:relay Team Composition에서
                         // 생성한 세션별 팀 파일을 로드
}

반환값:

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

---

list_pool_agents

팀 구성을 위해 사용 가능한 풀 에이전트를 모두 가져옵니다. 메타데이터만 반환하며 systemPrompt는 포함하지 않습니다. 세션 시작 전 사전 점검(pre-flight) 단계에서 사용합니다.

파라미터:

{
  agent_id: string; // 호출 에이전트 ID
}

반환값:

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

---

가시성

broadcast_thinking

에이전트의 현재 의도를 agent:thinking WebSocket 이벤트로 대시보드에 실시간 전송합니다. DB에 기록하지 않는 fire-and-forget 방식입니다. 에이전트의 tools 목록에 추가하고, 중요한 작업 전에 호출하세요.

파라미터:

{
  agent_id: string; // 호출 에이전트 ID
  content: string; // 에이전트가 하려는 작업 또는 현재 생각
}

반환값:

{
  success: true;
}

Tip

주요 작업 전에 broadcast_thinking을 호출하면 대시보드 Thoughts 패널에서 에이전트의 의도를 실시간으로 볼 수 있습니다.