Skip to content

MCP tools

Generated from the code by apps/docs/scripts/reference.mjs: edit the source, not this page.

wisp serves its tools over MCP. A task’s agent gets them on every run; wisp mcp serves them (stdio) to any agent or editor you point at it, so you can drive wisp from where you already work.

In a task

What an agent wisp runs can call.

Tool What it does Arguments (? optional)
ask_user Ask the user a question through wisp and wait for their answer. Use when a decision would change the rest of your work (ambiguous requirements, risky/destructive steps, choosing between approaches). The user may take minutes or hours to answer. Do not use it for trivial choices you can make yourself. question, context?, options?
resume_later Schedule a follow-up to this same task: at that time wisp sends your message back to you in this conversation, with your full context, as if the user had typed it. Use it when you must wait before you can go on (a deploy rolling out, CI running, a rate limit, “check again in 10 minutes”), or when the user asks you to do something later (“in 5 minutes do X”). After scheduling, end your turn with your report saying what you will check then; do not sleep or poll. Pass cancel with an id to drop one you scheduled. minutes?, at?, message?, cancel?
wisp_tag Tag this task with the topics it is about, so the user can find it later by searching wisp (⌘K, or #tag). Call it once you know what the task is about, in your first turn, and again only if the work moves to another topic: it replaces the tags. 3–8 short lowercase words or hyphenated terms a person would search for: the area or feature (auth, billing, search), the tech (redis, react, postgres), the kind of work (bugfix, refactor, research, release). Not the project name or words already in the title. tags
wisp_pr Attach a GitHub pull request to this task, so the user sees it on the task like one opened with Ship it: its state, checks and reviews, kept current, with Merge. Call it for every PR you open (gh pr create) or work on in this task, one call per PR; a task can have several. remove=true detaches one. pr, remove?
wisp_watch Let the user watch your work while you do it, instead of waiting for your answer: put up a page beside this task in wisp and keep it current as you go. Worth it for long or many-step work the user would like to follow (a migration across many files, a test or benchmark run, a crawl, a data job, a design taking shape); not for quick tasks or plain questions. You decide what the page shows and how: a progress bar and a checklist, a table filling in, a chart, a diagram growing. Two ways: a page you write that draws your progress, or the real thing running (the app you are building, on its dev server). action “open”: html (one self-contained page: inline CSS and JS; scripts, styles and fonts from https CDNs are fine; no fetch, no relative files), path (an .html file you wrote, read again on “reload”), or url (a running app, e.g. http://localhost:5173: start its dev server first, in the background), a title, and optionally run: { command, cwd, note }, how the user runs or checks the thing themselves (shown under the page). The page uses wisp’s theme as CSS variables (var(–ink), var(–muted), var(–line), var(–accent), var(–good), var(–bad), var(–surface), var(–sans), var(–mono)) and gets your data with wisp.on(‘state’, (s) => draw(s)) (called with the last state at once, then on every update; wisp.state is the last one). action “state”: state (JSON, up to 64 KB: what the page draws now; merge: true merges it into the last one), caption optional. Send it after each meaningful step, not on every keystroke. action “caption”: one line on what you are doing now. With a url: action “navigate” with path (“/settings”) or url shows the page you just changed; “reload” when hot reload missed it; “state” is for your own page only. action “reload”: after you edited the page. action “close”: when the work is done (the page stays, with its last state; a url keeps showing while its server runs). action, title?, html?, path?, url?, state?, merge?, caption?, run?
wisp_save Save something to the user’s My Stuff in wisp: their shelf of things kept from tasks (pictures, videos, documents, code, any file, links), where they browse and search them later. wisp keeps a copy, so it stays when the task or its folder goes. Call it when the user asks you to save or keep something for them (“save that to my stuff”, “keep the logo”), not on your own for everything you make. One item per call; give exactly one of path, text, url or app. For a bigger thing (slides, a demo, a small tool), build it as a static web app (index.html with its JS, CSS and assets; no server, no install step; bundle dependencies in or load them from a CDN) and save its folder as app: wisp serves and launches it for the user. With id, it updates an item they already have (a mentioned one, or from wisp_stuff) instead of adding one; the version before is kept. Show what you saved in your answer as a “stuff” block with its id. path?, text?, url?, app?, cover?, id?, name?, title?, note?, tags?, pin?, publish?
wisp_stuff List or search the user’s My Stuff in wisp: what they (or agents) saved from tasks, newest first, each with its title, kind, note, tags and the path of its file (or its url). Read-only. Use it when the user refers to something they saved (“use the logo from my stuff”): read or copy the file from its path. query?, id?, kind?, limit?
wisp_blocks The fields of answer blocks your instructions only name (graph, app), with an example. Read one before you put it in your final message. Read-only and answered at once. types
wisp_stats Read-only stats about the user’s past wisp tasks: how many tool calls each kind of action made (run = shell, read, edit, search, web, agent, tool = other MCP tools, ask), broken down by harness, project and day, plus turns, cost, tokens and success rate. Use when the user asks about their wisp usage, which tools or harnesses their tasks use, or what tasks cost. days?, agent?, project?
wisp_sessions List the user’s other wisp tasks, newest first: id, title, state (running | waiting | review | done), harness, project, last update and a one-line summary. Read-only. Use it to find a task the user refers to; read one with wisp_session. query?, state?, project?, archived?, limit?
wisp_session Read another wisp task by id: its title, state, harness, folder and branch, every request the user made in it, and a turn’s report as markdown (summary, diffs, tests, next steps). Read-only. Use it when the prompt mentions a wisp task (“@Title (wisp task )”) or the user asks what another task did. id, turn?
wisp_crew List the user’s crew in wisp: their long-lived agents, each with a name, role, brief, folder, harness, schedule and jobs. Read-only. Use it before changing a member, or when the user asks who is on their crew. With member: that one in full, their whole brief, notebook and kit (skills and instructions files, with their text), to read before you change their notebook or propose kit files. member?
wisp_crew_add Add a member to the user’s crew in wisp, when the user asks for one (“add a crew member who watches CI”), or when you need help for a job and the user’s brief lets you hire it. They work as tasks: on their schedule (cron), when the user tags @Name in a prompt, or when another task delegates to them. Write the brief to them, from what the user asked. Pick a short, friendly name if the user gave none. Returns the new member. When the user gives a shared crew file or link (“add the member from gist:abc123”), pass it as from instead. name?, role?, brief?, cwd?, agent?, model?, effort?, mode?, cron?, parallel?, paused?, avatar?, checkin?, from?
wisp_crew_edit Change a member of the user’s crew in wisp (rename, new brief, schedule, folder, harness, pause, notebook…) when the user asks. Only the fields given change. Their skills and instructions files aren’t set here: propose those with wisp_crew_kit. member, name?, role?, brief?, cwd?, agent?, model?, effort?, mode?, cron?, parallel?, paused?, avatar?, notebook?, remember?
wisp_crew_kit Propose skills or instructions files for a crew member’s kit, when the user asks you to give them, write or improve one (“give Gucci a skill for UI reviews”). A skill is a how-to for one kind of work, read when a job fits its description; an instructions file (rules, e.g. AGENTS.md) is followed on every job. Nothing changes yet: wisp shows the files under your answer, and the user reads them and picks what to add. The same name as one they have replaces it. Read the member with wisp_crew { member } first. Write each file for them: concrete steps, checklists, commands and paths, not generic advice. member, files
wisp_crew_remove Remove a member from the user’s crew in wisp. Their brief, notebook and schedule are deleted; their jobs stay as ordinary tasks. Only when the user asked to remove that member, or a member you added for a job is done; if unsure who they meant, ask the user first. A crew member’s job can’t remove that member itself. member
wisp_connectors List the user’s connectors in wisp: MCP servers that every task’s agent gets (in Edits and Full auto), whatever the harness. Each with its URL or command and whether it works, how many tools it has, or what it needs (a sign-in, a key). Read-only.
wisp_connector_add Add an MCP server to the user’s connectors in wisp, when the user asks (“add PostHog”, “connect Linear”). Remote: give its URL (for well-known services look up their official MCP URL, e.g. https://mcp.posthog.com/mcp). Local: give the command that starts it. Never pass secret values: list the names of the env vars (local) or headers (remote) it needs, and then call wisp_connector_signin, where the user signs in or types them. A local one asks the user first, since it runs a command on their computer. wisp checks it at once and says whether it works or what it needs. Tasks get it from their next turn. name, url?, command?, env?, headers?
wisp_connector_signin Show the user a card in this task to sign in to a connector (a Sign in button for servers with an account, like PostHog or Linear) or to type the keys it needs, and wait like ask_user. It ends on its own once the connector works, or when the user skips. Call it after wisp_connector_add or wisp_connectors says one needs a sign-in or keys. name, why?
wisp_available What the user has in wisp to run work on, in one read: harnesses on this computer (installed or not, models, thinking levels), their machines (other computers and cloud computers, online or not, the harnesses on each), projects, saved subagent presets, this task’s own subagents and the crew. Read-only. Read it before you pick a harness, model or machine for delegate or wisp_launch.
wisp_launch Start a new wisp task, as the user would from wisp’s prompt box: its own agent, conversation and card, which the user follows and replies to on its own. Use it when the user asks you to start, kick off or hand off tasks (“start a task to…”, “open a new conversation for…”, “run this on my devbox”); for help with your own work, use delegate instead. Returns the new task’s id at once (wait=true blocks until it finishes or asks). Show each task you start in your answer as a “task” block. prompt, project?, cwd?, scratch?, also?, machine?, agent?, model?, effort?, mode?, worktree?, goal?, factory?, formula?, subagents?, preset?, wait?, timeout_seconds?
wisp_task Act on another wisp task, as the user would from its card. action: reply (a follow-up, or the answer when it is asking; agent, model, effort or mode switch it from then on; queue=true waits for its current run instead of interrupting), stop, done (mark it done), archive, unarchive, rename (title), or wait (block until it finishes or asks, then return its report). Only when the user asks, or for tasks you started. Find tasks with wisp_sessions. task, action, text?, queue?, mode?, agent?, model?, effort?, title?, timeout_seconds?
approve Internal: wisp asks the user to approve a tool call your permissions do not allow on their own. Never call this yourself. tool_name, input?, tool_use_id?
subagent_results Wait for delegated tasks and return their reports. Pass the ids delegate returned; with none, every task delegated in this turn. ids?, wait?
wisp_plugins The plugins the user has: their own first (on or off, untrusted unless they trusted one), each in plain words with where it shows, what it may do, its folder and its whole wisp-plugin.json; then wisp’s built-in ones, one line each. Read-only. Use it before writing or changing a plugin.
wisp_plugin_schema The complete reference for writing a wisp plugin the user installs (the untrusted tier): manifest fields, the UI module’s wisp API, kit descriptors (components, props, events), tokens, parts and icons, where it may show, every command it may call with the permission it needs, and worked examples. Read-only.
wisp_plugin_data Run a read-only wisp command a plugin would call (wisp.call) and return a sample of its real answer, so the plugin reads the right fields. Only commands that read, and only those this task may run. Read-only. command, args?
wisp_plugin_check Check a plugin without installing it. Returns ok and what it does in plain words, or every problem to fix. Nothing of it runs: the manifest goes through wisp’s own checker and each UI module’s text is read for what fails in its sandbox. manifest, files?

From your agent or editor (wisp mcp)

What wisp mcp offers outside a task.

Tool What it does Arguments (? optional)
wisp_launch Hand a coding task to a background agent in wisp. The agent works autonomously in the given folder and ends with a presentation (summary, diffs, test results). Returns the session id at once; pass wait=true to block until it finishes or asks a question. Use for independent, well-scoped tasks that can run in parallel with your own work. prompt, project?, cwd?, also?, agent?, mode?, model?, effort?, worktree?, goal?, factory?, formula?, subagents?, preset?, machine?, wait?, timeout_seconds?
wisp_list List wisp sessions, newest first, with state (running | waiting | review | done) and a one-line summary. state?, cwd?, limit?
wisp_get Read a session: its state and the latest presentation as markdown (diffs, tests, next steps), plus any question the agent is waiting on. id
wisp_wait Block until a session finishes or asks a question, then return it like wisp_get. Returns early with timed_out if it is still running. id, timeout_seconds?
wisp_reply Send a follow-up to a session; it resumes the same agent conversation. If the agent is waiting on a question, this answers it. A follow-up sent while it runs interrupts it (queue=true waits for the run to finish instead). mode switches the session’s mode from this follow-up on. agent / model / effort switch the harness, model or thinking level from this follow-up on (see wisp_agents); a new harness is handed the conversation so far. id, text, queue?, mode?, agent?, model?, effort?
wisp_stop Stop a running session. id
wisp_agents Which harnesses are installed, with their models and thinking levels, and the user’s machines (other computers, cloud computers) with theirs.