Connect an agent to workspaces, tasks and notes with MCP

tokenstat's MCP server gives an agent access to local usage reports, registered project folders, tasks, notes, automations and workflows. Give the default instructions below to your agent. It can reuse an existing connection, find the local executable where it has access, and remember your preference. Manual installation and configuration are further down this guide. The server supplies descriptions and input schemas for all 49 tools once connected.

Start here: copy the default agent instructions

Paste this into an agent conversation or your project's agent instructions. It includes connection discovery for all three platforms and asks the agent to save your tokenstat preference in its supported global memory or user-level instructions. An agent without local access can give you setup steps; an agent without persistent memory can return a note for you to save. The prompt does not assume a particular client's configuration or memory-file location.

Remember tokenstat on this machine.

- tokenstat's MCP server is a local stdio server named `tokenstat`. If it is already configured in this client, reuse it.
- If it is missing and you have shell/filesystem access, find the executable: `command -v tokenstat` on macOS/Linux (installer default ~/.local/bin/tokenstat) or `(Get-Command tokenstat -ErrorAction SilentlyContinue).Source` on Windows (default %LOCALAPPDATA%\tokenstat\tokenstat.exe). Resolve the real home/LOCALAPPDATA, never copy YOUR_USERNAME literally. Verify the file exists.
- Configure a stdio MCP server named tokenstat with that absolute path and args ["mcp"] (standalone tokenstat-mcp uses args []). Use this client's MCP setup, do not overwrite other servers. Reconnect if needed. No port or API key. The macOS app bundle holds the host helper, not the MCP server. A browser-only agent needs a client-supported local bridge. Windows MCP covers archive tools; workspace/task/note/job tools need the Unix host (run tokenstat or tokenstat-hostd on macOS/Linux).
- Save in this agent's global memory or user instructions: use tokenstat for work tracking and project notes; the server name, verified command path, args, stdio transport, platform limits, tokenstat://guide, and workspace_list -> workspace_context. Paths and workspace IDs are machine-specific, recheck per machine and project. Merge with existing instructions. No credentials or note bodies in memory. If memory is unavailable, say so and return a short note to save.

When I ask about tokenstat, usage, projects, tasks or notes, use the tokenstat MCP tools:

1. Call workspace_list, match this project's absolute folder path to its workspace ID. If missing, workspace_add the existing absolute path. Never invent an ID or use a path as workspaceId.
2. Read workspace_context with {id} for one project, or {} for all projects.
3. `projects` is historical usage, not folder discovery. workspace_context takes `id`; list tools take `workspaceId` (omit = all workspaces, "" = unassigned only on list). task_list and note_list accept includeArchived and query; use includeArchived=true for older cards.
4. Read tokenstat://guide and the tool descriptions when unsure.

What belongs in global memory

Remember the preference and the verified connection details, not the contents of your work. Store the MCP server name, command path, arguments, transport, platform limits, guide URI and workspace discovery sequence. Paths and workspace IDs are machine-specific. On a new computer, rediscover the executable and workspace.

Project decisions and handoff notes belong in tokenstat notes under their workspace ID. They do not need to be duplicated into the agent's global memory. Saving a memory note does not register an MCP server in a different client; each client still needs its own connection configuration.

How the agent learns what is available

The tool descriptions are the callable reference. Ask the agent to read them when it needs exact inputs. Workflows use host-shaped graph objects; use workflow_get before replacing a graph. Automation updates likewise use the complete job object from automation_list.

Find the right project before adding work

1. Call workspace_list and match the intended folder's absolute path.
2. If it is missing, call workspace_add with its existing absolute path. This registers a folder; it does not create a directory.
3. Use the returned ID. Never put a display name or filesystem path in workspaceId.
4. Call workspace_context with {"id":"WORKSPACE_ID"} to read that project's context. Call it with {} for all registered folders and all unassigned cards.
5. Search existing tasks and notes before creating a duplicate.

The projects tool reports historical usage by project. It is not the registered workspace list and does not provide IDs for creating tasks.

Omitting workspaceId when creating a card makes it global/unassigned. Omitting it when listing means all workspaces. An empty string selects only unassigned cards on list tools. workspace_context uses id, not workspaceId.

Create a task or save a memo

Pass this object to task_create, replacing the workspace ID:

{
  "title": "Prepare the release",
  "notes": "Run checks and record remaining blockers.",
  "workspaceId": "REPLACE_WITH_WORKSPACE_ID"
}

Pass this object to note_create for project memory:

{
  "title": "Release handoff",
  "notes": "Decision: keep the current migration order. Remaining work: verify the import on a fresh archive.",
  "workspaceId": "REPLACE_WITH_WORKSPACE_ID"
}

Notes are board cards with kind: "note"; their body is the notes field. They cannot be delegated. task_list includes both kinds unless filtered. note_list always selects notes. task_get can read either kind, including archived cards. Note-specific read/update/remove tools reject task IDs.

Updates preserve omitted fields. To finish a task, call task_update with:

{
  "id": "REPLACE_WITH_TASK_ID",
  "column": "done"
}

Columns are backlog, doing, done and archive. Use includeArchived: true when a completed card is absent from a default list. Removal permanently deletes a card; moving it to archive keeps it available for later lookup.

Tool reference

All 49 tools are listed below. id means the record ID named in the description; workspaceId is a registered folder ID. Unless noted, optional inputs can be omitted.

Usage: 8 tools

Workspaces: 6 tools

Tasks: 7 tools

Notes: 5 tools

Agent backends: 1 tool

Automations: 11 tools

A job requires id, name, backend, workspaceId, prompt, budgetSeconds and enabled. Use an empty id on creation to generate one. Optional model and effort come from backend discovery. An omitted schedule is manual-only. Schedule kinds are once, interval, daily, weekdays, weekly and custom. Intervals use everySeconds (at least 60); wall-clock schedules use local hour and minute. Weekly schedules use weekday (Monday = 0) or the weekdays bitmask (Monday = bit 0); custom schedules use that bitmask. Saving an enabled recurring schedule allows the scheduler to run it when due.

Workflows: 11 tools

Run work deliberately

Creating a task or note does not execute it. To run a task, first discover a backend, bind the card to its workspace and backend with task_update, then call task_delegate. Read task_get for delegation state. Its delegate.runId is the ID to pass to automation_transcript. task_stop takes the card ID.

MCP results enter the calling agent's context and may be processed by its provider. Results can include project names, paths, task/note bodies and transcripts. A local connection does not make the calling agent offline.

Delegated tasks and automation/workflow runs may edit files, execute commands, contact services, incur provider charges or change Git state. Review these operations according to your client's approval settings. workflow_design invokes a backend to produce a draft; workflow_run is a separate action.

These tools do not expose account sync or public-profile publication. They do not provide general chat control, an arbitrary host-RPC tool, or a remote MCP HTTP endpoint.

Advanced setup and installation

Install the tokenstat CLI. Its mcp command starts the server. On macOS or Linux, find the installed executable:

command -v tokenstat

The installer uses ~/.local/bin/tokenstat on both macOS and Linux. Replace YOUR_USERNAME in the matching configuration below with your account's home folder name, or use the exact result of command -v tokenstat for a custom installation. Use a full absolute path: MCP clients may not expand ~ or $HOME in JSON.

macOS default installation

{
  "mcpServers": {
    "tokenstat": {
      "command": "/Users/YOUR_USERNAME/.local/bin/tokenstat",
      "args": [
        "mcp"
      ]
    }
  }
}

Linux default installation

{
  "mcpServers": {
    "tokenstat": {
      "command": "/home/YOUR_USERNAME/.local/bin/tokenstat",
      "args": [
        "mcp"
      ]
    }
  }
}

Windows default installation: archive tools

The Windows installer uses %LOCALAPPDATA%\tokenstat\tokenstat.exe. This usually expands to the path below. Use the actual LOCALAPPDATA location on your machine; JSON paths need escaped backslashes.

{
  "mcpServers": {
    "tokenstat": {
      "command": "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\tokenstat\\tokenstat.exe",
      "args": [
        "mcp"
      ]
    }
  }
}

To locate it in PowerShell:

(Get-Command tokenstat -ErrorAction SilentlyContinue).Source
Join-Path $env:LOCALAPPDATA 'tokenstat\tokenstat.exe'

Archive tools are available on Windows. Workspace, task, note, automation and workflow tools need the Unix host and are not available through Windows MCP.

Add the entry to your agent client's MCP configuration, then restart or reconnect the client. The configuration file's location depends on the client. If it provides a setup form, enter the executable path as the command and mcp as its argument.

The macOS app in Applications bundles tokenstat-hostd, which is the host helper, not the CLI MCP server. Install the CLI as well; do not use the app's GUI executable or its bundled host helper as the MCP command.

Build the standalone server

The standalone tokenstat-mcp executable is another option. Set its absolute path as command and use "args": []. To build it from a tokenstat source checkout with the repository's Rust toolchain:

cargo build --release -p tokenstat-mcp

The executable is target/release/tokenstat-mcp inside that checkout.

Keep the tokenstat app or tokenstat-hostd running under the same user on the same Unix machine for workspace, task, note and job management. These tools communicate with the host through its local Unix socket. Windows host management is not supported by this MCP transport. Archive tools work without the host. Refresh the archive when needed:

tokenstat scan

Does it need a web port or API key?

No. The client launches a local process and exchanges newline-delimited JSON-RPC through stdin/stdout. There is no MCP HTTP endpoint to visit, no listening web port to configure, and no tokenstat API key needed for this local connection.

An agent cannot automatically find an executable that its client has not registered. A browser-only agent needs a client-supported bridge to local MCP; it cannot access your computer by visiting tokenstat.ai. The hosted read API is a separate interface for usage data, not a remote version of these 49 tools.

Troubleshooting

Related

• MCP server and copyable setup
• Install tokenstat
• Workspaces and agent sessions
• Which command shows what
• Hosted usage read API