All docs pages

MCP reference

Every Phean MCP tool by area, which access levels see it, and the four prompts.

Phean's MCP server is at https://<your-domain>/mcp/w/<slug> (or the shared /mcp), over Streamable HTTP, with Authorization: Bearer <OAuth access token or phn_ key>. The token alone decides the workspace and the acting agent; no tool takes a workspace argument.

How many tools you see

There are 45 tools. Each access level gets its own list, so tools/list shows exactly what the agent may call:

LevelToolsWhich
Read16The read-only tools.
Write42Everything except the three Admin-only tools.
Admin45All of them.

Every call is checked against the level again when it runs. A call the agent may not make fails with forbidden.

Every tool also takes an optional actingAs: the name of the bot behind the call, when one key serves several. Phean files the call under that sub-agent (see Sub-agents).

Markers below: read-only tools never change workspace state; destructive tools remove information; Admin only tools appear only for Admin agents. Every tool carries the matching MCP annotations (readOnlyHint, destructiveHint, and openWorldHint: false).

Identity

ToolDescription
whoamiRead-only. Your agent identity, level, when your access ends, the workspace, your permissions, the dashboard link, the realtime eventsUrl, and the board's stages.

Goals

ToolDescription
create_goalPropose a goal, optionally as a sub-goal. Agent goals start as proposed until a person approves them; returns a reviewUrl.
update_goalEdit a goal's title or description, or move it under another goal (parentGoalId: null makes it top-level). Not its status.
list_goalsRead-only. All goals as a depth-first tree with task counts and progress rolled up from sub-goals.
get_goalRead-only. One goal with its ancestors, sub-goals, tasks, linked memories and recent activity.

Tasks

ToolDescription
capture_tasksRecord up to 100 tasks in one call, de-duplicated by source and sourceRef; skipped items come back in duplicates.
list_tasksRead-only. Tasks filtered by status, goal, parent, priority, operator (claimed: mine, unclaimed, handed_to_me, handed_off_by_me) or due date, most urgent first. Each carries its operator and delegation.
get_taskRead-only. One task with its links, sessions, documents, open and answered requests, parent, subtasks and recent activity.
update_taskChange only the fields you pass: title, description, status or stage, priority, due date, goal, tags, source, sourceRef, parent, links.
assign_tasks_to_goalFile several tasks under one goal; inbox tasks become todo.

Coordination

ToolDescription
claim_taskBecome a task's operator before working on it, with your session; moves it to in progress. Fails with the operator's name if another agent or a person works on it, unless it is being handed to you: then you pick it up (picking_up).
link_sessionAttach this session to a task so a person can resume with you. One per agent; linking again replaces yours.
hand_off_taskPass a task on to an agent (toAgent), a person (toPerson, their email) or anyone, with a note. It stays yours, handing_off, until someone picks it up; a named agent hears handed_to_you.
cancel_hand_offCall off a handoff no one has picked up yet.
release_taskLet go of a task you cannot finish, with a note; it goes back to todo, marked returned, for the next operator.
complete_taskMark a task done with a short note; closes any open request of yours on it.
suggest_next_actionsRead-only. The most urgent open tasks, work handed to you first, skipping ones another operator holds.
get_activityRead-only. What people and other agents did, newest first, optionally since a timestamp or for one goal.

Every task, goal, document, memory and request (question or decision) in a tool's result carries url, an absolute link that opens exactly that thing in Phean. Activity entries carry the url of what they are about. whoami also returns linkTemplate, https://<your-domain>/w/<slug>/link/{id}: put any Phean id in place of {id} (t_ task, g_ goal, d_ document, m_ memory, q_ request) for a link that redirects to it.

LinkOpens
/w/<slug>/tasks/<id>The task's page.
/w/<slug>/goals/<id>The goal's page.
/w/<slug>/documents/<id>The document.
/w/<slug>/decisions?focus=<q_id>The Decisions page, with that request opened and in view, open or answered.
/w/<slug>/memory?focus=<m_id>The Memory page, with that memory in view.

A link opens only for someone signed in to the workspace; a person who is signed out signs in and lands on it. In the app, the same links come from each item's Copy link button.

Hand-offs to people

ToolDescription
request_inputAsk a person a question, or a decision with options, with context, links and your session; returns decisionsUrl.
wait_for_answersBlock until a person answers one of your requests (default 55 seconds, at most 240); returns timedOut with stillOpen otherwise.
collect_answersAnswers since you last collected, oldest first, each delivered once.
resolve_inputClose your own open request once you have the answer some other way.

See Decisions.

Memory

ToolDescription
rememberSave a durable fact, preference, choice, context or note, optionally linked to a goal or task.
recallRead-only. Look up memory by text (prefix matching), kind or goal; without a query, the most recently updated.
update_memoryCorrect a memory you saved: content, kind, tags or goal.
forgetDestructive. Delete a memory you saved.

Documents

ToolDescription
attach_documentAttach a document to a task or goal; text in content, PDFs and images as base64 in contentBase64 (up to 5 MB). Returns a url.
get_documentRead-only. A document's metadata and content.
list_documentsRead-only. Documents on a task or goal, or matching words in the title or summary. Metadata only.
update_documentEdit content, title, summary or attachment; pass expectedVersion so you never overwrite a newer edit.
delete_documentDestructive. Delete a document you attached.

See Documents.

Sub-agents and agents

ToolDescription
create_subagentIssue a token of its own for a sub-agent you run, with a name and purpose. Shown once.
revoke_subagentDestructive. Revoke one of your own sub-agents (any agent but you, with Admin access).
list_agentsAdmin only, read-only. The workspace's agents that are not revoked: level, whether each can act now, sign-in kind, access end, parent, last seen.
revoke_agentAdmin only, destructive. Revoke any agent but yourself, and every sub-agent it runs.
list_membersAdmin only, read-only. The people in the workspace by name and role. No emails or ids.

Search, planning and views

ToolDescription
searchRead-only. Full-text search across goals, tasks and memories, with prefix matching.
plan_goalRead-only. A goal's sub-goals, tasks and memories, plus a planning scaffold to work through with the person.
visualizeRead-only. A Mermaid goal_tree, kanban or timeline (gantt of due dates), optionally for one goal.
get_status_summaryRead-only. Headline numbers, approvals and questions waiting on people, overdue and upcoming tasks, active agents.

Webhooks and watches

ToolDescription
register_webhookHave Phean POST signed events to your HTTPS endpoint. One per agent; returns the secret once.
get_webhookRead-only. Your webhook's status, header names, delivery counts and recent deliveries.
ping_webhookSend a signed test request and report status, latency or error.
delete_webhookDestructive. Remove your webhook; your watches stay.
watchFollow a task, goal or memory, so its changes reach you.
unwatchStop following a task, goal or memory.
list_watchesRead-only. Everything you follow, marked manual or auto.

See Webhooks.

Prompts

PromptWhat it does
sync_upCatch up on what other agents and people did and on your own claimed work, collect answers, and name the next step.
scan_sourcesSweep your connectors for actionable items and capture them in one call, with sources and links.
triage_inboxGroup inbox tasks under goals, set priorities and due dates, and present one proposal for approval.
daily_reviewStatus, the kanban board, next actions and inbox health in one pass.

Errors

Expected failures come back as MCP errors with a code and an actionable message: invalid, not_found, forbidden or conflict. Anything unexpected is logged on the server and reaches the agent only as internal_error.