Skip to content
StayFocus stayfocus.now
Back to home

StayFocus MCP server

Connect Claude, ChatGPT or any MCP client to your own StayFocus day: tasks, focus sessions, projects, experiments, notes and brain dump. OAuth 2.1, 24 tools, one endpoint.

Endpoint

https://stayfocus.now/mcp

Streamable HTTP · 24 tools · OAuth 2.1

Machine-readable copies of this page: /mcp.md · /mcp.json

Summary

StayFocus is an execution loop. Work descends through four levels: a project answers why, a task answers what, a next action answers what to do in the next five minutes, and a focus session is the block of time where it happens. Around that sit a daily loop (check in, commit to one thing, close the day), a brain dump for thoughts that are not work yet, time-boxed experiments, and a streak. The StayFocus MCP server lets an AI assistant read and write one authenticated user's own StayFocus data over the Model Context Protocol.

The fastest route into a user's day is get-today: it returns their check-in, the task they committed to, where they last stopped, the focus time the day still holds, and up to three ranked candidates that each say why they surfaced.

Every tool resolves the user from the authorizing token and scopes each query to that user. No tool can reach another user's data, billing data, or admin data.

Connection

Field Value
Endpoint https://stayfocus.now/mcp
Transport Streamable HTTP (POST, JSON-RPC 2.0)
Server name StayFocus
Server version 2.0.0
Tools 24
Resources / prompts None — tools only
Authentication OAuth 2.1 (authorization code + PKCE), or a bearer personal access token
Plan required Active subscription or trial (14-day free trial, no card)

Authentication

Two supported paths. Web connectors use OAuth; command-line clients that can set headers may use a bearer token instead.

Option A — OAuth 2.1 (Claude.ai, ChatGPT, any MCP web connector)

The user pastes only the endpoint URL. The client discovers and completes the flow automatically; no application registration with Anthropic or OpenAI is required.

GET  https://stayfocus.now/.well-known/oauth-protected-resource     # resource metadata
GET  https://stayfocus.now/.well-known/oauth-authorization-server   # authorization server metadata
POST https://stayfocus.now/oauth/register                           # dynamic client registration
GET  https://stayfocus.now/oauth/authorize                          # user approves the grant
POST https://stayfocus.now/oauth/token                              # authorization code + PKCE -> access token
POST https://stayfocus.now/mcp                                      # tool calls, Authorization: Bearer <token>

The issued token is bound to the user who approved the grant and carries the single scope mcp:use. The user can revoke it at any time in Settings → Account → AI assistant → Connected assistants.

Option B — bearer personal access token (desktop and CLI)

Generate a token in Settings → Account → AI assistant → Desktop & CLI (advanced). It is shown once. Send it on every request:

Authorization: Bearer <token>

Verify a token works:

curl -s -X POST https://stayfocus.now/mcp \
  -H "Authorization: Bearer $STAYFOCUS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Without a valid token the endpoint returns 401.

Client configuration

Claude.ai and Claude Desktop (web connector, OAuth)

  1. Open claude.ai/settings/connectors → Add custom connector.

  2. Name it StayFocus, paste https://stayfocus.now/mcp, confirm. There is no token field — none is needed.

  3. Enable StayFocus from the search & tools menu in a chat.

  4. On first use, approve the StayFocus grant screen. Claude Desktop and mobile sync the connector automatically.

Claude Code

# OAuth (recommended) — Claude Code opens the browser to authorize
claude mcp add --transport http stayfocus https://stayfocus.now/mcp

# Or with a personal access token
claude mcp add --transport http stayfocus https://stayfocus.now/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Claude Desktop config file

Settings → Developer → Edit Config, then add:

{
    "mcpServers": {
        "stayfocus": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://stayfocus.now/mcp"
            ]
        }
    }
}

ChatGPT

  1. Settings → Apps & Connectors, enable Developer mode (Plus, Pro, Team or Enterprise).

  2. Create, name it StayFocus, paste https://stayfocus.now/mcp, choose OAuth as the authentication method.

  3. Approve the StayFocus permission screen.

Any other MCP client

Point it at https://stayfocus.now/mcp with transport Streamable HTTP. Both OAuth and Authorization: Bearer are accepted.

Tools

24 tools — 9 read, 15 write. All parameters are JSON, passed as arguments to tools/call.

Tool Type Purpose
get-today read The single best call for "what should I be doing right now?" / "شنو ندير دابا؟" / "كيف هو نهاري؟"
record-arrival write Record how the user showed up today: clear, scattered, loaded, drained or charged
commit-to-task write Commit to one task as today's single most important thing, or decline a task that was suggested
close-day write Close the working day — StayFocus's shutdown ritual
get-tasks read List the user's tasks — the unit of work between a project and a focus session
create-task write Create a task — an outcome the user could finish in a few days
update-task write Edit an existing task: rename it, write or clear its next action, change its status, schedule it, or move it to a project
break-down-task write Split a task into smaller steps
get-focus-sessions read Get the authenticated user's focus session history: total count, total focused minutes, and the most recent sessions
get-active-session read Get the user's currently running or paused focus session, if any — including the task it is committed to, how long is left, and how many distractions have been logged
start-focus-session write Start a focus session
control-focus-session write Pause, resume, or log a distraction on the running focus session, without ending it
end-focus-session write End the running focus session and record how it went
get-projects read List the authenticated user's projects with status, visibility, description and how much open work each one holds
create-project write Create a new project for the authenticated user
get-stats read Get the authenticated user's numbers: streaks, total sessions, focused time, experiments, and the shape of their task list — how much is open, how much is actually startable, and how much has stalled
get-experiments read List the authenticated user's tiny experiments (time-bound commitments) and highlight the active one
get-notes read Search and read the authenticated user's notes — their decision log, reflections and progress journal from the "Updates" page
create-note write Create a private note in the user's decision log / reflection journal (the "Updates" page)
get-brain-dump-items read List items in the user's brain dump — the capture lane for thoughts and ideas that are not a project, experiment or note yet
capture-brain-dump-item write Capture a quick thought, idea or brain dump into the user's brain dump — for things that are not ready to become a project, experiment or note yet, or that should come back later
schedule-brain-dump-reminder write Schedule (or reschedule) a reminder on an open brain dump item, so it resurfaces in "needs attention" later
archive-brain-dump-item write Archive an brain dump item once the user is done with it — it will no longer show up in "needs attention"
convert-brain-dump-item write Turn a brain dump item into a task, a project, a tiny experiment, or a reflection — when the user has decided what to do with a captured idea

get-today

The single best call for "what should I be doing right now?" / "شنو ندير دابا؟" / "كيف هو نهاري؟". Returns the user's day in one shot: how they said they arrived this morning, the one task they committed to, where they last stopped and what they left open, how much focus time the day still has, and up to three ranked candidates with the reason each one surfaced. Read this before recommending anything — the candidates already account for deadlines, how cold the work has gone, and whether it fits the time left. Prefer this over get-tasks when the question is about today rather than about the whole list.

Parameters: none.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get-today"
    }
}

record-arrival

Record how the user showed up today: clear, scattered, loaded, drained or charged. Use it when they say how they are feeling about work at the start of a session or a day — "I am fried today" / "راسي مخربق" / "I feel sharp". It branches what the app offers them and it is deliberately never scored, averaged, or shown back as a verdict, so record it plainly and do not editorialise. One answer per day; answering again overwrites it, which is correct — someone scattered at nine and clear at eleven is telling the truth both times.

Parameter Type Required Description
state string (one of: clear, scattered, loaded, drained, charged) yes How the user arrived. clear: knows what to do. scattered: too many open loops. loaded: carrying something heavy. drained: low on fuel. charged: ready to push.
chose string no Optional: what they decided to do about it, in their own words.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "record-arrival",
        "arguments": {
            "state": "clear"
        }
    }
}

commit-to-task

Commit to one task as today's single most important thing, or decline a task that was suggested. Use commit for "let's do X today" / "غادي نخدم على هادي اليوم", and decline for "not that one". Declining is recorded on purpose rather than hidden: the same task turned down three days running is worth surfacing back to the user. Get candidates from get-today before choosing. Committing schedules the task for today; it does not start a timer, use start-focus-session for that.

Parameter Type Required Description
task_uuid string yes UUID of the task (see get-today candidates, or get-tasks).
decision string (one of: commit, decline) no Whether this is today's one thing, or a task the user turned down.
available_minutes integer no Commit only: how much focus time the day realistically holds. Defaults to what StayFocus already computes from the user's daily focus goal minus time already spent.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "commit-to-task",
        "arguments": {
            "task_uuid": "9f8c1e2a-7b4d-4c31-9a0e-5d6f7a8b9c0d"
        }
    }
}

close-day

Close the working day — StayFocus's shutdown ritual. Use it for "I am done for today" / "سالينا اليوم" / "let's wrap up". Two questions: what moved, and what should be waiting tomorrow. For a task that was scheduled but never moved, "carry" keeps it as it is, "shrink" clears its next action so a smaller step gets written, and "drop" lets it go — these are three different decisions and should not be treated as one. A day can only be closed once; check get-today's day_closed first.

Parameter Type Required Description
moved_note string no What moved today, in the user's own words.
stalled_task_uuid string no Optional: a task that was scheduled today but did not move (see get-tasks with filter="stalled").
stalled_decision string (one of: carry, shrink, drop) no What to do with that stalled task. carry: leave it alone. shrink: clear its next action so a smaller step gets written. drop: let it go.
tomorrow_task_uuid string no Optional: the task to have waiting tomorrow morning.
tomorrow_next_action string no Optional: the first concrete step for that task tomorrow, written now while the context is warm.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "close-day"
    }
}

get-tasks

List the user's tasks — the unit of work between a project and a focus session. Use this to answer "what am I working on?", "what's on my plate?", "what can I actually start?", "what's blocked?" / "شنو خاصني ندير؟" / "شنو بقا عليا؟". A task is startable only when it has a next action written; use filter="startable" for "what could I start right now", filter="inbox" for undecided tasks that still need a next action, and filter="stalled" for tasks scheduled repeatedly that never moved.

Parameter Type Required Description
filter string (one of: open, startable, inbox, scheduled_today, stalled, blocked, done, all) no Which slice of the task list to return. "open" (default) is everything not done or dropped.
project_uuid string no Optional: only tasks belonging to this project (see get-projects).
search string no Optional: match against the task title, outcome and next action.
limit integer no How many tasks to return, 1-50.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get-tasks"
    }
}

create-task

Create a task — an outcome the user could finish in a few days. Use this when the user has decided something is real work: "add a task", "I need to ...", "زيد هاد المهمة". Only the title is required. Writing a next_action is what makes a task startable, so include one whenever the user has said what the first concrete step is; without it the task lands in the inbox as undecided, which is the honest place for it. For a thought that is not work yet, use capture-brain-dump-item instead.

Parameter Type Required Description
title string yes What the task is, in the user's own words.
outcome string no Optional: what "done" looks like for this task.
next_action string no Optional but valuable: the smallest concrete first step. Writing one promotes the task from inbox to ready.
project_uuid string no Optional: the project this task belongs to (see get-projects).
energy string (one of: deep, light, admin) no The kind of attention the task needs. Defaults to deep.
estimate_minutes integer no Optional: how long the user thinks it will take.
due_on string no Optional: hard deadline as an ISO 8601 date (YYYY-MM-DD). Resolve relative dates yourself before calling.
scheduled_for string no Optional: the day the user intends to do it, as an ISO 8601 date (YYYY-MM-DD).

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "create-task",
        "arguments": {
            "title": "…"
        }
    }
}

update-task

Edit an existing task: rename it, write or clear its next action, change its status, schedule it, or move it to a project. Every field is optional — send only what changes. Use this for "the next step is ...", "mark that done" / "سالينا هادي", "I'm blocked on ...", "move that to tomorrow". Writing a next_action promotes an undecided task to ready; sending an empty next_action clears it and sends the task back to the inbox. Marking a task done also closes its open questions and its subtasks. To split a task into smaller steps, use break-down-task instead.

Parameter Type Required Description
task_uuid string yes UUID of the task to edit (see get-tasks).
title string no New title.
outcome string no New definition of done.
next_action string no The smallest concrete next step. Pass an empty string to clear it, which returns the task to the inbox.
status string (one of: inbox, ready, active, blocked, done, dropped) no New status. "ready" requires a next action, either already on the task or sent in the same call.
blocked_reason string no Only used with status "blocked": what the task is waiting on.
project_uuid string no Move the task to this project (see get-projects).
energy string (one of: deep, light, admin) no The kind of attention the task needs.
estimate_minutes integer no How long the user thinks it will take.
due_on string no Hard deadline as an ISO 8601 date (YYYY-MM-DD).
scheduled_for string no The day the user intends to do it, as an ISO 8601 date (YYYY-MM-DD).

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "update-task",
        "arguments": {
            "task_uuid": "9f8c1e2a-7b4d-4c31-9a0e-5d6f7a8b9c0d"
        }
    }
}

break-down-task

Split a task into smaller steps. This is the answer to a task that keeps getting scheduled and never moves, and to "this feels too big" / "هادي كبيرة بزاف" / "قسمها ليا". The steps become subtasks, and the first one becomes the task's next action when it does not have one yet. Check get-tasks with filter="stalled" to find the tasks most likely to need this.

Parameter Type Required Description
task_uuid string yes UUID of the task to break down (see get-tasks).
steps array of string yes The smaller steps, in the order they should be done. Each one should be small enough to start without thinking.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "break-down-task",
        "arguments": {
            "task_uuid": "9f8c1e2a-7b4d-4c31-9a0e-5d6f7a8b9c0d",
            "steps": []
        }
    }
}

get-focus-sessions

Get the authenticated user's focus session history: total count, total focused minutes, and the most recent sessions.

Parameters: none.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get-focus-sessions"
    }
}

get-active-session

Get the user's currently running or paused focus session, if any — including the task it is committed to, how long is left, and how many distractions have been logged. Also reports a session that has just finished and is still waiting to be closed with an outcome, so an assistant can ask how it went instead of losing the block.

Parameters: none.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get-active-session"
    }
}

start-focus-session

Start a focus session. Attach it to a task whenever there is one — a task carries its own project, prefills the intention from its next action, and is what lets end-focus-session record an outcome and log the time against the work. Falling back to a project or an experiment still works, and passing nothing starts a quick unattached block that can be filed later. Idempotent: if a session is already running it is returned unchanged instead of starting a second one.

Parameter Type Required Description
task_uuid string no Preferred. UUID of a startable task (see get-tasks with filter="startable", or get-today candidates). The task supplies the project and, if intention is omitted, the intention.
project_uuid string no UUID of one of the user's projects (see get-projects). Use only when no task fits.
experiment_uuid string no UUID of one of the user's running experiments (see get-experiments).
intention string no What the user will work on during this session. Required unless task_uuid is given, in which case the task's next action is used.
duration_minutes integer no Planned session length in minutes (15, 25, 50 or 90).

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "start-focus-session"
    }
}

control-focus-session

Pause, resume, or log a distraction on the running focus session, without ending it. Use "pause" for "hold the timer" / "وقف الوقت", "resume" for "I am back" / "رجعت", and "log-distraction" when the user notices they got pulled away — the count is a record, never a judgement. Pausing keeps the session alive; resuming pushes the expected end time out by however long it was paused. To finish the session, use end-focus-session.

Parameter Type Required Description
action string (one of: pause, resume, log-distraction) yes What to do with the running session.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "control-focus-session",
        "arguments": {
            "action": "pause"
        }
    }
}

end-focus-session

End the running focus session and record how it went. A finished timer is not an outcome, so ask the user what actually happened and pass it: "finished" completed the next action, "progress" moved it, "stuck" hit a wall, "not_started" never really began. When the session was attached to a task, this is also what logs the time against that task, writes the note the user will see when they pick it back up, and stores the questions they are leaving open — skip those and the record of their afternoon is wrong. Outcome defaults to "progress" when omitted. Safe to call twice: it does nothing if no session is running and never overwrites an outcome that was already recorded.

Parameter Type Required Description
outcome string (one of: finished, progress, stuck, not_started) no What actually happened in the block. Defaults to "progress".
note string no What happened, in the user's words. With outcome "stuck" this becomes the task's blocked reason.
resume_context string no The note to the user's future self: where exactly they stopped, so picking it back up is cheap.
next_action string no The smallest concrete step for next time. Writing one now, while the context is warm, is what makes returning easy.
open_questions array of string no Things the user did not know when they stopped. They resurface on the resume card.
completes_task boolean no Only honoured with outcome "finished": marks the whole task done, not just this block.
mood integer no Optional reflection, 1 rough, 2 okay, 3 good, 4 great.
reflection_note string no Optional free-text reflection on the block.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "end-focus-session"
    }
}

get-projects

List the authenticated user's projects with status, visibility, description and how much open work each one holds. A project is the why; the tasks inside it are the what — use get-tasks with a project_uuid to see them.

Parameters: none.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get-projects"
    }
}

create-project

Create a new project for the authenticated user. Projects are private by default.

Parameter Type Required Description
name string yes The project name.
description string no Optional short description of the project.
visibility string (one of: private, public) no Project visibility. Defaults to private.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "create-project",
        "arguments": {
            "name": "…"
        }
    }
}

get-stats

Get the authenticated user's numbers: streaks, total sessions, focused time, experiments, and the shape of their task list — how much is open, how much is actually startable, and how much has stalled. Use it for "how am I doing?" / "كيفاش خدمت هاد الأسبوع؟". For what to do right now rather than how much has been done, use get-today.

Parameters: none.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get-stats"
    }
}

get-experiments

List the authenticated user's tiny experiments (time-bound commitments) and highlight the active one.

Parameters: none.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get-experiments"
    }
}

get-notes

Search and read the authenticated user's notes — their decision log, reflections and progress journal from the "Updates" page. Use this to answer questions like "what did I decide about X", "summarize my recent notes on project Y", or "search my notes for...". The user may ask in Arabic (e.g. "ملاحظاتي", "قراراتي", "مذكراتي") — treat that the same as "notes". Filter by free-text search, a project, or tags.

Parameter Type Required Description
search string no Free-text search within note content. Leave empty to list recent notes.
project_uuid string no Only return notes linked to this project (see get-projects for uuids).
tags array of string no Only return notes tagged with at least one of these tags.
limit integer no Maximum number of notes to return (1-50).

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get-notes"
    }
}

create-note

Create a private note in the user's decision log / reflection journal (the "Updates" page). Use this when the user wants to record a decision, write down a reflection, log progress, or asks to "save this as a note" — including Arabic phrasing like "خليه كملاحظة" or "سجل هاد القرار". Optionally link the note to a project (get-projects for the uuid), tag it, and set a mood.

Parameter Type Required Description
content string yes The note content — the decision, reflection or progress update to record.
project_uuid string no Optional: link this note to one of the user's projects (see get-projects for uuids).
tags array of string no Optional tags for this note (max 5).
mood_key string (one of: motivated, focused, excited, proud, grateful, hopeful, calm, tired, bored, stuck, confused, stressed, anxious, frustrated, overwhelmed, sad, lonely, angry) no Optional mood associated with this note.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "create-note",
        "arguments": {
            "content": "…"
        }
    }
}

get-brain-dump-items

List items in the user's brain dump — the capture lane for thoughts and ideas that are not a project, experiment or note yet. By default returns items that need attention: open items plus scheduled reminders that are now due. Use this to answer "what's in my brain dump?" / "شنو عندي فتفريغ الذهن دابا؟" or to check for reminders that just came due. Each item shows its uuid, content, status (open, scheduled, converted, archived) and whether a reminder is due.

Parameter Type Required Description
status string (one of: needs_attention, open, scheduled, converted, archived, all) no Which items to return. "needs_attention" (default) is open items plus due reminders.
limit integer no Maximum number of items to return (1-50).

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get-brain-dump-items"
    }
}

capture-brain-dump-item

Capture a quick thought, idea or brain dump into the user's brain dump — for things that are not ready to become a project, experiment or note yet, or that should come back later. Use this whenever the user says things like "save this idea", "add this to my brain dump", "remind me about this later", or in Arabic "احفظ هاد الفكرة" / "خزن هاد الشي". Only the content is required — capture is zero-friction by design. The user can later ask to schedule a reminder, convert it to a project/experiment/note, or archive it.

Parameter Type Required Description
content string yes The thought, idea or note to capture.
focus_session_uuid string no Optional: the uuid of the user's currently active/paused focus session, if this idea came up mid-session (see get-active-session).

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "capture-brain-dump-item",
        "arguments": {
            "content": "…"
        }
    }
}

schedule-brain-dump-reminder

Schedule (or reschedule) a reminder on an open brain dump item, so it resurfaces in "needs attention" later. Use this when the user says "remind me about this on Friday at 9am", "ذكرني بها يوم الجمعة" or similar. Get the item's uuid from get-brain-dump-items. Provide either "remind_at" with a concrete ISO 8601 date-time you computed from the user's request (must be in the future), or a "preset" (in_1_hour, tomorrow, next_week).

Parameter Type Required Description
item_uuid string yes UUID of the brain dump item (see get-brain-dump-items).
remind_at string no A concrete future date-time, ideally ISO 8601 (e.g. 2026-06-19T09:00:00). Resolve relative phrases like "next Friday at 9am" to a real date yourself before calling this tool.
preset string (one of: in_1_hour, tomorrow, next_week) no A quick preset instead of remind_at. "tomorrow" and "next_week" mean 9:00 local time.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "schedule-brain-dump-reminder",
        "arguments": {
            "item_uuid": "9f8c1e2a-7b4d-4c31-9a0e-5d6f7a8b9c0d"
        }
    }
}

archive-brain-dump-item

Archive an brain dump item once the user is done with it — it will no longer show up in "needs attention". Use this when the user says they're done with an idea, want to dismiss it, or "no longer need" something from their brain dump. Get the item's uuid from get-brain-dump-items.

Parameter Type Required Description
item_uuid string yes UUID of the brain dump item (see get-brain-dump-items).

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "archive-brain-dump-item",
        "arguments": {
            "item_uuid": "9f8c1e2a-7b4d-4c31-9a0e-5d6f7a8b9c0d"
        }
    }
}

convert-brain-dump-item

Turn a brain dump item into a task, a project, a tiny experiment, or a reflection — when the user has decided what to do with a captured idea. "task" is usually the right answer and the most common one: it is a single outcome the user could finish in a few days, and it arrives undecided on purpose, so follow up with update-task once they say what the first step is. Use "project" for something with many tasks in it, "experiment" for a time-boxed try, "note" for a reflection worth keeping. Use this for "turn this into a task" / "حولها لمهمة", "make this a project" / "حولها لمشروع", "save this as a reflection" / "احفظها كتأمل". Get the item's uuid from get-brain-dump-items. For "experiment", you may optionally pass duration_days, success_criteria and visibility.

Parameter Type Required Description
item_uuid string yes UUID of the brain dump item (see get-brain-dump-items).
target string (one of: task, project, experiment, note) yes What to convert the brain dump item into.
duration_days integer no Experiment only: how many days the experiment should run. Defaults to 14.
success_criteria string no Experiment only: what success looks like for this experiment.
visibility string (one of: private, public) no Experiment only: visibility of the new experiment. Defaults to private.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "convert-brain-dump-item",
        "arguments": {
            "item_uuid": "9f8c1e2a-7b4d-4c31-9a0e-5d6f7a8b9c0d",
            "target": "task"
        }
    }
}

Errors

Response Meaning
401 Unauthorized Missing, expired or revoked token. Re-authorize the connector, or generate a new personal access token.
403 Forbidden The account has no active subscription or trial. See Pricing.
405 Method Not Allowed The request used GET or DELETE on the endpoint. MCP messages are POST only.
429 Too Many Requests Rate limit exceeded. Back off and retry.
JSON-RPC isError: true The tool ran but rejected the input — for example an unknown UUID, or a second start-focus-session while one is already running. The message text explains what to change.

Limits and rules

Related