FocusBox MCP — 도구 레퍼런스

커넥터 URL: https://focusbox.io/mcp/api. 설정 방법은 /mcp 에서 확인하세요.

list_today

사용자가 오늘 일정으로 등록한 작업(미완료만)을 반환합니다.

인자

없음.

반환값

배열 항목 타입: { taskId, name, durationSeconds, projectId }.

응답 예시

[
  { "taskId": "abc", "name": "Write spec", "durationSeconds": 1500, "projectId": "mytasks" }
]

next_task

다음에 시작할 작업 하나를 반환합니다. 다음 캘린더 일정까지 남은 시간에 맞는지, 이전 날짜에서 미뤄졌는지, 바로 시작할 만큼 작은지를 기준으로 고릅니다. 선택 이유와 대안 두 개, 바로 시작할 수 있는 링크가 함께 제공됩니다.

인자

availableMinutes (1-480, 선택).

반환값

{ task, alternatives, freeWindowMinutes, busyNow, message }.

응답 예시

{
  "task": {
    "taskId": "abc", "name": "Finish pricing page", "projectId": "work",
    "estimateMinutes": 35, "source": "rollover",
    "reason": "Carried over from 2 days ago; fits the 47 min you have before your next meeting.",
    "startUrl": "https://focusbox.io/now?id=work&taskId=abc"
  },
  "alternatives": [],
  "freeWindowMinutes": 47, "busyNow": false,
  "message": "Start here: Finish pricing page (35 min)."
}

get_streams

사용자의 FocusBox 프로젝트 목록을 반환합니다(작업을 담는 컨테이너로, 과거 명칭에 따라 API에서는 "streams"라고 부릅니다). 보관된 프로젝트와 today/mytasks 버킷은 제외됩니다.

인자

없음.

반환값

배열 항목 타입: { streamId, name }.

add_task

프로젝트에 새 작업을 추가하거나 오늘 일정에 등록합니다. 기본 시간은 25분입니다.

인자

반환값

{ taskId, streamId, name, durationSeconds }.

update_task

기존 작업의 하나 이상의 필드(name, durationSeconds 또는 dueDate)를 수정합니다.

인자

반환값

{ taskId, streamId, name, durationSeconds, dueDate }.

delete_task

작업을 영구 삭제합니다. 멱등성: 이미 삭제된 작업을 다시 삭제해도 오류가 아닙니다.

인자

반환값

{ taskId, streamId, deleted, reason? }.

complete_task

FocusBox 작업을 완료 처리합니다.

인자

반환값

{ taskId, streamId, completed: true }.

get_insights_30d

최근 30일간 사용자가 완료한 작업의 요약 집계입니다.

인자

없음.

반환값

{ totalTasks, totalFocusMinutes, topStreams[{streamId, name, tasks}, days: 30 }].

인증

OAuth (Claude에 권장)

Claude Desktop과 claude.ai 웹은 OAuth 플로우를 자동으로 완료합니다. API key를 직접 다룰 필요가 없습니다.

Bearer (Cursor, Inspector, 커스텀 클라이언트)

API key는 다음에서 발급받으세요: /account/api-keys (apikey_로 시작). 모든 요청에 Authorization: Bearer apikey_xxx로 전송하세요.

레이트 리밋

API key당 2분에 300회 도구 호출. IP당 2분에 60회 미인증 프로브. 둘 중 하나라도 초과하면 Retry-After 헤더와 함께 HTTP 429를 반환합니다.

FAQ