Cherry Studio injects first-party tools into your session over four MCP servers
(mcp__cherry-tools__*, mcp__agent-memory__*, mcp__skills__*, mcp__mcp-manager__*)
and gives shell-capable general agents bundled runtimes for local execution. The MCP
tools act on the running app — the user's knowledge bases, IM channels, schedules,
managed CLIs, skill library, and MCP server registry — through boundaries only Cherry
owns. Shell and file tools cannot reach those app boundaries correctly; use the bundled
runtimes only for the local execution cases routed below.
This file is a router. It carries only the global rules and the intent → tool → reference table. Each reference holds that domain's prerequisites, sequencing, conditional availability, output interpretation, recovery, and examples. Read the one reference the task needs (and any it cross-links to) before calling — don't work from this page alone.
Tool names here are fully qualified (mcp__server__tool); the exact names exposed in
your session are authoritative if they ever differ. This guide never restates argument
shapes — the live tool schema in your session is the authoritative source for
parameter names, enums, and required fields. Read it before every call.
npm install, git clone, crontab, or hand-edit
knowledge or MCP settings files to accomplish these — the tool does bookkeeping (registration, scoping, approval, sync)
that a raw shell command skips. Shell is fine for inspection (e.g. command -v to
probe PATH) — just not to perform the owned mutation.mcp__cherry-tools__kb_manage, mcp__cherry-tools__cli_install,
mcp__cherry-tools__session_create, mcp__cherry-tools__session_send,
mcp__skills__install_skill, and mcp__mcp-manager__install_mcp_server are gated by
the session's approval mode. Call them only once the user's intent is clear; if approval is
declined, stop and report — do not retry the same effect through another route.| User intent | Route to | Reference |
|---|---|---|
| Look up current/online facts, news, docs | mcp__cherry-tools__web_search → mcp__cherry-tools__web_fetch |
web.md |
| Browser interaction (click, forms, screenshots) | mcp__browser__* when enabled; load cherry-browser |
web.md |
| Answer from the user's own documents | mcp__cherry-tools__kb_list → mcp__cherry-tools__kb_search → mcp__cherry-tools__kb_read |
knowledge.md |
| Add / delete / re-index knowledge | mcp__cherry-tools__kb_manage (resolve IDs first; needs approval) |
knowledge.md |
| Read or convert a local document | mcp__cherry-tools__to_markdown → read the returned temporary Markdown path as needed |
documents.md |
| Recall a past fact, correction, or preference | mcp__agent-memory__memory (search) before re-asking |
memory.md |
| Save durable knowledge vs. a one-off event | mcp__agent-memory__memory (update vs. append) |
memory.md |
| Schedule a recurring / future task | mcp__cherry-tools__cron (Cherry scheduling only) |
autonomy.md |
| Proactively message the user or send a file | mcp__cherry-tools__notify (needs configured recipients) |
autonomy.md |
| Inspect / connect / repair IM channels, rename agent | mcp__cherry-tools__config |
autonomy.md |
| Find, create, message, or inspect work across Agent Sessions | mcp__cherry-tools__session_list / session_search / session_create / session_send / session_deliveries |
sessions.md |
| Generate an image | mcp__cherry-tools__generate_image (needs a painting model) |
outputs.md |
| Declare final deliverable file(s) | mcp__cherry-tools__report_artifacts |
outputs.md |
| Run JS/TS or Python, invoke a one-off package, search local code/files | bundled bun, uv / uvx, or rg according to task lifetime |
cli.md |
| Find / install a command-line tool | command -v check → mcp__cherry-tools__cli_list → mcp__cherry-tools__cli_search → mcp__cherry-tools__cli_install (approval) |
cli.md |
| Find / install a new capability skill | mcp__skills__search_skills → mcp__skills__install_skill (approval) |
skills.md |
| Register a new MCP server the user supplied | mcp__mcp-manager__install_mcp_server (approval; never invent the config) |
mcp.md |
Two different situations, don't confuse them:
mcp__cherry-tools__generate_image with no painting model. It stays listed and
returns a note; relay the note and point the user at configuration — don't retry
blindly or fake success.On any tool error result (bad ID, unsupported channel/file, invalid recipe), read the message and correct the call; don't silently retry the same arguments. On declined approval, stop and report — never re-attempt the mutation through a different route.
Not covered here: SDK-native Read/Edit/Bash and orchestration tools; calling the
tools of a third-party (user-configured) MCP server — only registering one is in scope,
see mcp.md; the AI-SDK chat read_file attachment reader (a
chat-path tool, not exposed on this MCP surface); and the role-specific
mcp__assistant__* navigation/diagnosis tools, which belong to the Cherry Assistant and
its own guide.