FocusBox MCP — tool reference

Connector URL: https://focusbox.io/mcp/api. See /mcp for setup.

list_today

Returns the user's tasks scheduled for today (incomplete only).

Arguments

None.

Returns

Array of { taskId, name, durationSeconds, projectId }.

Example response

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

next_task

Returns one task to start next, chosen by what fits the time before the next calendar event, what has carried over from earlier days and what is small enough to begin. Includes the reason, two alternatives and a link to start.

Arguments

availableMinutes (1-480, optional).

Returns

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

Example response

{
  "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

List the user's FocusBox projects (containers for tasks; called "streams" in the API for historical reasons). Archived projects and the today/mytasks buckets are excluded.

Arguments

None.

Returns

Array of { streamId, name }.

add_task

Add a new task to a project or schedule it for today. Default duration is 25 minutes.

Arguments

Field	Type	Required	Description
`streamId`	string	required	Target project id from get_streams. Use "today" (or "mytasks") for today.
`name`	string	required	Task title (1-500 chars).
`durationSeconds`	number	optional	60-14400 (1 min — 4 h). Default 1500.
`dueDate`	string	optional	Optional Unix-seconds timestamp for when the task is scheduled. The Today view shows tasks whose due falls in today's window in the user's timezone.
`clientRequestId`	string	optional	Idempotency key. The same key within 5 minutes returns the cached result.

Returns

{ taskId, streamId, name, durationSeconds }.

update_task

Update one or more fields of an existing task: name, durationSeconds, or dueDate.

Arguments

Field	Type	Required	Description
`streamId`	string	required	Stream id from get_streams. Use "today" or "mytasks" for the inbox.
`taskId`	string	required	Task id from list_today or get_streams.
`name`	string	optional	New task title (1-500 chars).
`durationSeconds`	number	optional	New duration in seconds (60-14400). Resets durSecInit to the new value.
`dueDate`	number	optional	New due date as a Unix-seconds timestamp.
`clientRequestId`	string	optional	Idempotency key. The same key within 5 minutes returns the cached result.

Returns

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

delete_task

Permanently delete a task. Idempotent: deleting an already-deleted task is not an error.

Arguments

Field	Type	Required
`streamId`	string	required
`taskId`	string	required

Returns

{ taskId, streamId, deleted, reason? }.

complete_task

Mark a FocusBox task as complete.

Arguments

Field	Type	Required
`streamId`	string	required
`taskId`	string	required

Returns

{ taskId, streamId, completed: true }.

get_insights_30d

Aggregate summary of the user's completed tasks over the last 30 days.

Arguments

None.

Returns

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

Authentication

OAuth (recommended for Claude)

Claude Desktop and claude.ai web complete the OAuth flow automatically. No API key handling needed.

Bearer (Cursor, Inspector, custom clients)

Get your API key at /account/api-keys (starts with apikey_). Send as Authorization: Bearer apikey_xxx on every request.

Rate limits

300 tool calls per 2 minutes per API key. 60 unauthenticated probes per 2 minutes per IP.

FAQ

Authentication: OAuth or Bearer?

Both. Use OAuth (handled automatically by Claude Desktop and claude.ai web) for the smoothest setup. For Cursor, MCP Inspector, or any custom client, use Bearer auth with apikey_<uuid> from /account/api-keys.

What are the rate limits?

300 tool calls per 2 minutes per API key. 60 unauthenticated probes per 2 minutes per IP. Hitting either returns HTTP 429 with a Retry-After header.

How long do OAuth tokens last?

30 days from issuance. After that Claude triggers a re-authorisation automatically. The token is opaque (at_*) and stored on the server side; no refresh token is needed.

Why does my Claude session reconnect after a deploy?

The MCP session map is in-process on a single ECS task. A rolling deploy resets it. Claude reconnects automatically and resumes; you should see no user-visible interruption beyond a brief reload.

Can I use streaming responses (SSE)?

Yes. The transport is the MCP-spec streamable HTTP variant, so each tool call may stream progress events before the final result. Sessions are kept alive with periodic ping frames.