MCP

toryo speaks Model Context Protocol, so an agent session can search your knowledge plane, look at what is running, and start work, without a /-command or the board.

toryo mcp install                 # wire it into the MCP clients you have
toryo mcp list                    # what is wired where
toryo mcp uninstall               # remove it

toryo setup offers to do the install as a prompted step. It is an offer rather than a service: these are config files toryo does not own, so an unattended run never edits them silently.

The server runs as a child process over stdio. Nothing listens on a port and nothing is exposed to the network.

What you get#

Roughly twenty-five tools in three groups.

Knowledge, reading and writing the same stores your agent runs use:

Tool	Does
`brain_search`	one ranked search across memory, library, and the code index
`memory_recall` `memory_remember` `memory_rate`	recall, record, and rate memories
`library_search` `library_get`	search and fetch authored documents
`code_search`	ask what a codebase contains
`code_map`	orient in a codebase: its load-bearing files
`dispute_query` `dispute_record`	look up and record recorded disagreements
`idea_add`	file an idea

Control plane, for looking at and steering work:

Tool	Does
`project_list` `project_resolve`	your registered projects
`sequence_list` `sequence_run`	what can run, and start one
`sequence_status` `sequence_runs`	one run, or recent runs
`sequence_ack`	answer a gate a run is waiting on
`dispatch_enqueue` `dispatch_status` `dispatch_list`	queue a job, check one, list them
`schedule_create` `schedule_list`	recurring work
`ideas_list`	the idea backlog

The escape hatch, which is how the other ~180 CLI commands stay reachable without paying for ~180 tool schemas in every session:

Tool	Does
`toryo_help`	discover what a CLI can do
`toryo_run`	run a CLI command

What toryo_run reaches is derived from the contract manifest, so a command added to any app widens it automatically.

What it will not run#

toryo_run withholds two classes of command, by role rather than by name:

Process lifecycle, migrate, start, daemon, serve, watch, up, down, restart, and the rest. foreman and toryo setup own these.
Destructive or interactive, forget, reset, remove, delete, dismiss, deactivate, the cleanup-* family, psql. These stay behind a terminal, where you can see what you are about to run.

A refusal names the shell command to run instead, so it redirects rather than dead-ends.

cancel is deliberately reachable. It is recoverable, and it is the stop button you want when you are looking at a run from Claude Desktop and it is going somewhere wrong.

Claude Code, Claude Desktop, Codex, GitHub Copilot and Cursor#

toryo mcp install wires every one of them it finds. Narrow it with --client claude-code|claude-desktop|codex|copilot|cursor.

Client	Where it lands	Worth knowing
Claude Code	`~/.claude.json`	Wired through its own CLI when that is on your PATH, by merging into the file when it is not.
Claude Desktop	`claude_desktop_config.json`	Created when absent, and needs a restart to pick the server up.
Codex	`~/.codex/config.toml`	Written by `codex mcp add`, which corrects a stale entry in place and leaves your comments and unrelated tables alone. Found by the `codex` binary on your PATH.
GitHub Copilot	`~/.copilot/mcp-config.json`	Created when absent. No restart needed: copilot reads it per session. Found by the `copilot` binary on your PATH.
Cursor	`~/.cursor/mcp.json`	Created when absent. Writing the file is the whole job: Cursor picks the server up on its own, and all twenty-five toryo tools show up, alongside whatever other servers you have.

Every JSON config goes through one backup-then-merge path: your other MCP servers survive, and every mutating write is preceded by a timestamped backup. Codex is the exception, because its config is TOML and its own CLI owns the write.

~/.claude.json is never created from nothing. That file holds much more than MCP servers, so if it is absent, Claude Code has not run on this machine yet, and creating it would be toryo inventing state for another tool.

Project scoping is per call, in every client#

There is no session project, and no client-specific behaviour to learn. Every project-scoped tool takes a project argument, a slug or a UUID, and resolves it on the call. Name a project and the tool answers about that project and its descendants; omit it and you get global scope, which every read states in its own scope field rather than leaving you to infer it from a short answer.

That was not always true. The server used to resolve its own working directory to a project at startup, which meant the same question answered differently in Claude Code and in Claude Desktop, where there is no meaningful working directory to resolve. Naming the project is now the only behaviour.

The refs a tool accepts come from:

toryo project list

Skills or tools?#

Both surfaces exist and they overlap.

Skills (/toryo-code, /toryo-status, …) are a harness-side surface: toryo skills install writes them into both user-level skills roots (~/.claude/skills, ~/.agents/skills). They read files, run shell, and hold a multi-turn flow, so they are the richer path for anything needing judgement or file access on the way in.

Tools work in every wired client (Claude Code, Claude Desktop, Codex, GitHub Copilot and Cursor), and are the only surface Claude Desktop has: it is an app, not a harness with a skills root. They are one typed call with a structured result.

Where a gesture exists as both, prefer the skill in Claude Code.

Worker attachment#

Interactive client installation and worker attachment are separate. Each worker launch negotiates the MCP capability of the selected harness, then attaches the toryo Brain server and any requested browser server for that run. Claude Code, Codex, Copilot, and Cursor all support this attachment, but each receives it through its own native configuration shape. A run that opts out does not inherit an interactive client's user-level servers by accident.

Cursor receives attached servers through a run-local --plugin-dir. Its .cursor-plugin/plugin.json manifest points to mcp.json in that plugin directory. Both files live with the run, so attachment does not modify user or project Cursor configuration.

Codex needs one extra generated setting: each attached server is written with tool approval enabled. Codex's broader non-interactive approval policy does not approve MCP calls by itself; without the server setting Codex can list the tools but cancels every call. toryo writes this into the per-run config rather than changing your user config.

The rule underneath all of it#

The MCP is a second facade over the CLI, not a parallel API. Nothing exists in a tool that a CLI command cannot already do, which is why the escape hatch can be generated from the contract rather than hand-maintained. If you are building something on toryo, build on the CLI: see Building on toryo.

When something is missing#

The tools are not there. Run toryo mcp list to see what is wired. Restart Claude Desktop after any change; it does not reload config.

Everything comes back global. The call named no project. Every read says so in its own scope field. See above.

Searches return nothing. Check services with toryo foreman check. The server starts even when Postgres is down. It just has nothing to read.

A command is refused. It is in one of the withheld classes. The refusal names the shell command to run instead.