Context and search

7 tools. Each one is also a REST route and a CLI command, from the same definition: the same input, the same output, the same errors.

Tool	What it does	Kind
`get_context`	Get the prioritised workspace context	Read · idempotent · no outside service
`get_stats`	Read the raw activity events	Read · idempotent · no outside service
`list_activity`	The feed	Read · idempotent · no outside service
`list_realtime_events`	List realtime events since a cursor	Read · idempotent · no outside service
`search`	Search the workspace	Read · idempotent · no outside service
`whoami`	Identify the account and the server date	Read · idempotent · no outside service
`send_flame`	Send a flame	Write · no outside service

get_context

Get the prioritised workspace context. The entry point to call first. Returns, in one call: the workspace counters, the tasks scored highest by the prioritisation engine (with the reasons behind each score), the active projects and the areas. The score combines the deadline, the scheduled date, the priority and whether the task belongs to a project. Calendar blocks are excluded.


Kind	Read · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`GET https://api.doers.sh/v2/context`
CLI	`doers context get`
Touches	`areas`, `projects`, `tasks`, `user`
Operation	`getContext`

Input

Field	Type	Required	Default	Allowed values	Description
`limit` (query)	integer	no	`15`	1 to 50	No description in the registry.
`day` (query)	string	no		`YYYY-MM-DD`	Reference day in YOUR timezone. Defaults to the server’s UTC day.

Output

Output fields

Field	Type	Allowed values	Description
`day`	string
`counts`	object
`counts.open`	integer	-9007199254740991 to 9007199254740991
`counts.overdue`	integer	-9007199254740991 to 9007199254740991
`counts.dueToday`	integer	-9007199254740991 to 9007199254740991
`counts.doneLast7Days`	integer	-9007199254740991 to 9007199254740991
`topPriorities`	object[]
`topPriorities[].id`	string
`topPriorities[].title`	string
`topPriorities[].score`	number
`topPriorities[].reasons`	string[]
`topPriorities[].when`	object		How the task is scheduled (distinct from its `deadline`).
`topPriorities[].when.kind`	string	`today`, `anytime`, `someday`, `date`
`topPriorities[].when.date`	string (optional)
`topPriorities[].when.hasTime`	boolean (optional)
`topPriorities[].when.time`	string \| null (optional)
`topPriorities[].deadline`	string \| null
`topPriorities[].project`	string \| null
`projects`	object[]
`projects[].id`	string
`projects[].name`	string
`projects[].openTaskCount`	integer	-9007199254740991 to 9007199254740991
`areas`	object[]
`areas[].id`	string
`areas[].name`	string

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_context",
    "arguments": {
      "limit": 15,
      "day": "2026-09-22"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "3 open task(s), 3 overdue, 3 due today.\nPriorities:\n- [bd3d1324-95a8-4d65-8637-2d8f94e5c165] Prepare the Acme quarterly review · Notes for the Acme launch."
      }
    ],
    "structuredContent": {
      "day": "2026-09-22",
      "counts": {
        "open": 3,
        "overdue": 3,
        "dueToday": 3,
        "doneLast7Days": 3
      },
      "topPriorities": [
        {
          "id": "bd3d1324-95a8-4d65-8637-2d8f94e5c165",
          "title": "Prepare the Acme quarterly review",
          "score": 3,
          "reasons": ["Notes for the Acme launch."],
          "when": {
            "kind": "today"
          },
          "deadline": "2026-09-22",
          "project": "Notes for the Acme launch."
        }
      ],
      "projects": [
        {
          "id": "244210e4-8437-4655-8980-a70249a99369",
          "name": "Acme",
          "openTaskCount": 3
        }
      ],
      "areas": [
        {
          "id": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
          "name": "Acme"
        }
      ]
    }
  }
}

doers context get --limit 15 --day 2026-09-22

get_stats

Read the raw activity events. Completions and sessions since since, plus every day plan, all unaggregated. Bucketing by day or hour happens in the caller’s timezone, so the server returns moments rather than buckets: an hour histogram computed here would be wrong for everyone outside UTC. Plans are keyed by local day, which since cannot be compared against without that same timezone, so they are not windowed.


Kind	Read · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`GET https://api.doers.sh/v2/stats`
CLI	`doers stats get`
Touches	`coachPlanTasks`, `coachPlans`
Operation	`getStats`

Input

Field	Type	Required	Default	Allowed values	Description
`since` (query)	number	yes			Epoch milliseconds.

Output

Output fields

Field	Type	Allowed values	Description
`completions`	object[]
`completions[].id`	string
`completions[].title`	string
`completions[].completedAt`	number		Epoch milliseconds.
`completions[].projectId`	string \| null
`completions[].areaId`	string \| null
`sessions`	object[]
`sessions[].id`	string
`sessions[].taskId`	string \| null
`sessions[].title`	string
`sessions[].startedAt`	number		Epoch milliseconds.
`sessions[].endedAt`	number \| null		`null` while the session is still running.
`sessions[].visibility`	string	`public`, `anonymized`, `private`	What the activity feed may show of it. Private until shared at the session’s end.
`plans`	object[]
`plans[].day`	string	`YYYY-MM-DD`	Local day key, `YYYY-MM-DD`.
`plans[].taskIds`	string[]

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_stats",
    "arguments": {
      "since": 3
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "1 completed · 1 session(s) · 1 plan(s)."
      }
    ],
    "structuredContent": {
      "completions": [
        {
          "id": "21606b58-37ee-4917-8e56-cff2afe21083",
          "title": "Prepare the Acme quarterly review",
          "completedAt": 1790069400000,
          "projectId": "244210e4-8437-4655-8980-a70249a99369",
          "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf"
        }
      ],
      "sessions": [
        {
          "id": "3f3af1ec-ebbd-4410-8b41-7ec0d27bbfcb",
          "taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c",
          "title": "Prepare the Acme quarterly review",
          "startedAt": 1790069400000,
          "endedAt": 1790069400000,
          "visibility": "public"
        }
      ],
      "plans": [
        {
          "day": "2026-09-22",
          "taskIds": ["0ebb429f-a86d-481c-8630-fac53db1c91c"]
        }
      ]
    }
  }
}

doers stats get --since 3

list_activity

The feed. Finished sessions shared by the people you follow, and your own, newest first. A public one names the task; an anonymized one names only where it lived; a private one is not here.


Kind	Read · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`GET https://api.doers.sh/v2/activity`
CLI	`doers activity list`
Touches	`areas`, `follows`, `projects`, `sessionFlames`, `tasks`, `user`, `workSessions`
Operation	`listActivity`

Input

This tool takes no arguments.

Output

Output fields

Field	Type	Allowed values	Description
`items`	object[]
`items[].session`	object
`items[].session.id`	string
`items[].session.startedAt`	number		Epoch milliseconds.
`items[].session.endedAt`	number		Epoch milliseconds.
`items[].session.visibility`	string	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private.
`items[].person`	object
`items[].person.username`	string
`items[].person.name`	string
`items[].person.image`	string \| null
`items[].minutes`	integer	0 to 9007199254740991
`items[].title`	string \| null		The task’s title; the owner always sees it; a follower only when the session is public.
`items[].container`	string \| null		The project or area the task lived in, whatever the visibility.
`items[].flames`	integer	0 to 9007199254740991
`items[].flamed`	boolean		Whether the caller sent one.
`items[].isMe`	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_activity",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "- @ada · 30 min on Prepare the Acme quarterly review · 🔥 3"
      }
    ],
    "structuredContent": {
      "items": [
        {
          "session": {
            "id": "3f3af1ec-ebbd-4410-8b41-7ec0d27bbfcb",
            "startedAt": 1790069400000,
            "endedAt": 1790069400000,
            "visibility": "public"
          },
          "person": {
            "username": "ada",
            "name": "Acme",
            "image": "https://acme.example/ada.png"
          },
          "minutes": 30,
          "title": "Prepare the Acme quarterly review",
          "container": "Notes for the Acme launch.",
          "flames": 3,
          "flamed": true,
          "isMe": true
        }
      ]
    }
  }
}

doers activity list

list_realtime_events

List realtime events since a cursor. Returns this account’s events on the one realtime log, oldest first, after since. That id is the resume token: reconnect with it to fill a gap. An omitted since starts from the oldest retained event. A channel narrows to one stream (inbox, a place, a run, or activity). This read does not mark anything read.


Kind	Read · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`GET https://api.doers.sh/v2/realtime/events`
CLI	`doers realtime list-realtime-events`
Touches	`realtimeEvents`
Operation	`listRealtimeEvents`

Input

Field	Type	Required	Default	Allowed values	Description
`since` (query)	string	no		UUID	Last event id already received. Omit to start from the oldest.
`channel` (query)	string	no		1 to 120 characters	One stream. Omit to read every channel for this account.
`limit` (query)	integer	no	`50`	1 to 200	How many events to return.

Output

Output fields

Field	Type	Allowed values	Description
`events`	object[]
`events[].id`	string
`events[].channel`	string
`events[].kind`	string	`message`, `needs-approval`, `share-invite`, `coach-brief`, `run-status`, `read`
`events[].title`	string
`events[].body`	string \| null
`events[].deepLink`	string
`events[].createdAt`	number		Epoch milliseconds.
`cursor`	string \| null	UUID	Id of the last event in this page, or null when empty.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_realtime_events",
    "arguments": {
      "since": "6b5a3ded-016a-4782-8989-8c6e38d09f71",
      "channel": "Notes for the Acme launch."
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "1 event(s), cursor 46a4eebd-20d8-41ec-8c0e-cb54f6d83465."
      }
    ],
    "structuredContent": {
      "events": [
        {
          "id": "b8e1f80b-d70a-4078-8c78-55a451731b74",
          "channel": "Notes for the Acme launch.",
          "kind": "message",
          "title": "Prepare the Acme quarterly review",
          "body": "Notes for the Acme launch.",
          "deepLink": "https://acme.example/brief",
          "createdAt": 1790069400000
        }
      ],
      "cursor": "46a4eebd-20d8-41ec-8c0e-cb54f6d83465"
    }
  }
}

doers realtime list-realtime-events --since 6b5a3ded-016a-4782-8989-8c6e38d09f71 --channel "Notes for the Acme launch."

search

Search the workspace. Text search across task titles, project names and area names. Use this before asking the user for an identifier.


Kind	Read · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`GET https://api.doers.sh/v2/search`
CLI	`doers context search`
Touches	`areas`, `projects`, `tasks`, `user`
Operation	`search`

Input

Field	Type	Required	Default	Allowed values	Description
`query` (query)	string	yes		2 to 200 characters	No description in the registry.
`kinds` (query)	string[]	no		each: `task`, `project`, `area`	Restrict the search. Defaults to all three.
`limit` (query)	integer	no	`20`	1 to 50	No description in the registry.

Output

Output fields

Field	Type	Allowed values
`results`	object[]
`results[].kind`	string	`task`, `project`, `area`
`results[].id`	string
`results[].label`	string
`results[].detail`	string \| null

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "Acme",
      "limit": 20
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "- [f6a214f7-a5fc-4a0c-8cee-9660b7fc29f5] (task) Acme"
      }
    ],
    "structuredContent": {
      "results": [
        {
          "kind": "task",
          "id": "f6a214f7-a5fc-4a0c-8cee-9660b7fc29f5",
          "label": "Acme",
          "detail": "Notes for the Acme launch."
        }
      ]
    }
  }
}

doers context search Acme --limit 20

whoami

Identify the account and the server date. Returns the token holder’s profile and the workspace counters. nextUsernameChangeAt is null when the username can be changed now, and a moment otherwise: a username is a public URL, so it moves at most once a fortnight. Important about dates: the server does not know your timezone and reasons in UTC. serverDay is the current UTC day. If your timezone differs, pass day explicitly to the operations that accept it.


Kind	Read · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`GET https://api.doers.sh/v2/me`
CLI	`doers context whoami`
Touches	`areas`, `projects`, `tasks`, `user`
Operation	`whoami`

Input

This tool takes no arguments.

Output

Output fields

Field	Type	Allowed values
`userId`	string
`name`	string \| null
`email`	string \| null
`username`	string \| null
`image`	string \| null
`usernameUpdatedAt`	number \| null
`nextUsernameChangeAt`	number \| null
`serverDay`	string
`serverTime`	number
`counts`	object
`counts.openTasks`	integer	-9007199254740991 to 9007199254740991
`counts.projects`	integer	-9007199254740991 to 9007199254740991
`counts.areas`	integer	-9007199254740991 to 9007199254740991

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "whoami",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Account ada · 3 open task(s) · server day 2026-09-22."
      }
    ],
    "structuredContent": {
      "userId": "04f8996d-a763-47a9-89b1-028ee3007569",
      "name": "Acme",
      "email": "ada@acme.example",
      "username": "ada",
      "image": "https://acme.example/ada.png",
      "usernameUpdatedAt": 1790069400000,
      "nextUsernameChangeAt": 1790069400000,
      "serverDay": "2026-09-22",
      "serverTime": 3,
      "counts": {
        "openTasks": 3,
        "projects": 3,
        "areas": 3
      }
    }
  }
}

doers context whoami

send_flame

Send a flame. The one reaction. One per person per session; a second is a no-op. Only on a session you can see, and never on your own.


Kind	Write · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`POST https://api.doers.sh/v2/sessions/{sessionId}/flames`
CLI	`doers activity send-flame`
Touches	`areas`, `follows`, `projects`, `sessionFlames`, `tasks`, `user`, `workSessions`
Operation	`sendFlame`

Input

Field	Type	Required	Default	Allowed values	Description
`sessionId` (path)	string	yes			No description in the registry.

Output

Output fields

Field	Type	Allowed values	Description
`item`	object
`item.session`	object
`item.session.id`	string
`item.session.startedAt`	number		Epoch milliseconds.
`item.session.endedAt`	number		Epoch milliseconds.
`item.session.visibility`	string	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private.
`item.person`	object
`item.person.username`	string
`item.person.name`	string
`item.person.image`	string \| null
`item.minutes`	integer	0 to 9007199254740991
`item.title`	string \| null		The task’s title; the owner always sees it; a follower only when the session is public.
`item.container`	string \| null		The project or area the task lived in, whatever the visibility.
`item.flames`	integer	0 to 9007199254740991
`item.flamed`	boolean		Whether the caller sent one.
`item.isMe`	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "send_flame",
    "arguments": {
      "sessionId": "3f3af1ec-ebbd-4410-8b41-7ec0d27bbfcb"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: 🔥 3"
      }
    ],
    "structuredContent": {
      "item": {
        "session": {
          "id": "3f3af1ec-ebbd-4410-8b41-7ec0d27bbfcb",
          "startedAt": 1790069400000,
          "endedAt": 1790069400000,
          "visibility": "public"
        },
        "person": {
          "username": "ada",
          "name": "Acme",
          "image": "https://acme.example/ada.png"
        },
        "minutes": 30,
        "title": "Prepare the Acme quarterly review",
        "container": "Notes for the Acme launch.",
        "flames": 3,
        "flamed": true,
        "isMe": true
      }
    }
  }
}

doers activity send-flame --session-id 3f3af1ec-ebbd-4410-8b41-7ec0d27bbfcb

MCP server

Tool reference

Context and search

get_context

Input

Output

Example

get_stats

Input

Output

Example

list_activity

Input

Output

Example

list_realtime_events

Input

Output

Example

search

Input

Output

Example

whoami

Input

Output

Example

send_flame

Input

Output

Example

​get_context

​Input

​Output

​Example

​get_stats

​Input

​Output

​Example

​list_activity

​Input

​Output

​Example

​list_realtime_events

​Input

​Output

​Example

​search

​Input

​Output

​Example

​whoami

​Input

​Output

​Example

​send_flame

​Input

​Output

​Example

get_context

Input

Output

Example

get_stats

Input

Output

Example

list_activity

Input

Output

Example

list_realtime_events

Input

Output

Example

search

Input

Output

Example

whoami

Input

Output

Example

send_flame

Input

Output

Example