MCPs and skills

Use the MCPs & Skills row on the home screen to choose which MCP servers, skills and extensions a repository's sessions load. Everything is enabled by default, and Mercury saves your changes to those defaults. Mercury calls this selection a kit. A session receives its kit when it starts and keeps it for its lifetime.

A connected MCP server's tool descriptions and schemas reach the model whole, and Mercury reports the first request's size. stdio MCP servers terminate their child process tree and close their pipes even when a headless session exits during server startup, and an MCP tool call that is aborted, times out or loses its socket after the request could have been sent returns an error naming the interrupted or unknown outcome without replaying the call. When a configured MCP server exits immediately at startup or fails to answer within its 30-second connection deadline, Mercury reports the failure and reason both to you (as a notice row in chat and on stderr in headless runs, naming the command it spawned and the first line of stderr) and to the model (as a system note so it knows the server's tools are unavailable). In an untrusted folder, mercury mcp list, mercury mcp get <name>, mercury health --json and the MCP gauge state that the folder is not trusted and that its project MCP servers from .mercury/mcp.json were not loaded.

MCP: Configured servers, extension servers and eligible account connectors, by their resolved names, each on or off. A server an extension ships is named ext:<extension>:<server>. Session-only servers, including Mercury's built-in mercury server, are not listed.
Skills: Added directory skills from the user, project and managed settings (discovered and hot-reloaded up to eight folders deep under a skills directory), and extension skills, each on, invocable or off. Bundled skills load in sessions but are not listed (the bundled mercury-docs skill includes only git-tracked documentation files). Skills an MCP server supplies are available once a session connects that server, and the menu does not list them.
Extension master row: Sits above the extension's items in each section it contributes to. Items under an off master read off (extension) and keep their own state underneath.
NEXT SESSION: Counts the listed entries the next session gets; built-in capabilities are outside the count.

The menu shows no added MCPs or no added skills when its inventory is empty. Those messages count only the added entries. Items are on unless the saved configuration says otherwise, and each toggle is saved immediately. The menu and session runner use the same item list, so the menu does not list items that the session cannot see.

Skill states

on: Ambient. The agent can reach for the skill when needed.
invocable: Listed, but loaded only when you enter /<name>.
off: Absent from the next session.

Image generation

The bundled image-generation skill helps with prompts, reference edits, masks, pixel art, editable pipelines, ComfyUI workflows, upscaling and video. Ask for an image or edit in plain language. It reads the installed models and defaults before rendering, keeps the chosen model unless you request a change, and returns the saved image path. Downloads still need your approval. Local generation uses your computer's time, disk and memory; a selected rented GPU keeps billing during setup and rendering.

For editable work, it saves a pipeline file, checks its steps and runs from the step you change. See Local images and video for setup, tools and saved files. Installation and sign-in questions use the bundled mercury-docs skill instead.

Change the next session's kit

To change the next session's kit:

Select the MCPs & Skills row on the home screen.
Press Enter.
Move to the server, skill or extension row with ↑ or ↓.
Press Enter to change its state.
Press Esc to return to the home screen.
Start a new session.

The new session starts with a kit resolved from the record against the live roster, checked as it is handed to the session and stamped on the session's durable record.

Backspace restores a row's default. An extension is live for a session only when both its installed switch and its master row in that repository agree. A kit narrows only the session it was stamped on: crewmates, the daemon and every non-session process are untouched. The warm runner behind New Session already holds the next session's kit, so a menu edit costs one cold spawn before the pool is warm again.

Save a preset

To save a preset, open the MCPs & Skills menu with the wanted states set, press p and name the preset. Mercury saves the current changes as a named preset stored globally, so it travels across repositories.

Up to 200 presets are stored. A preset's changes resolve against whatever repository uses it. A skill or extension the preset turns off stays off by name, so it also applies to a member that arrives later. An MCP server the preset excludes is absent from the membership. Entries naming members the repository lacks are counted in the preset receipt.

Use a preset for the next session

To use a preset for the next session, press w in the MCPs & Skills menu, select the preset with ↑ or ↓, press Enter and start a new session. The home screen's MCPs & Skills row reads next: preset '<name>', the next session created uses that preset, and the menu's own choices resume afterwards.

Enter on the selected preset's row clears the selection. Backspace in the preset roster deletes a preset. Resuming a dead transcript while a preset is selected applies it, and switching into a live session never consumes it. A coordinator can launch a session with a preset by name, and an unknown name is a typed refusal naming the saved roster. Launch receipts say how the kit arrived: kit carried, kit derived or kit preset.

Session controls

/mcp: Inspects this session's MCP servers, signs in, browses each connected server's tools and parameters, reconnects, or toggles a server on or off for this chat. Pressing Enter (↵) on a needs sign-in row starts authentication from the active runner, and expanding a connected MCP server opens a filterable tools list and a per-tool parameter schema detail view with Esc stepping back one level at a time. When an MCP server's tools change through notifications/tools/list_changed or /mcp reconnect, the conversation's bound tool list does not move: an unreferenced deferred tool takes the live schema, while a tool already bound or referenced in the conversation receives a tool_schema_delta attachment with its updated parameters. User-scope MCP servers added mid-session (mercury mcp add -s user …) become available in the running chat right away. Mercury's built-in servers answer a typed exemption.
/skills: This session's skills, cycling on, invocable and off.

These dials are session-scoped and write no configuration file. A dial turned mid-turn is queued whole and applies when the turn ends, so the record never says off over a process still holding the member. Each applied dial lands a kit-dial receipt on the session. The per-repository record has exactly one writer, the menu.

A resumed or reactivated session is re-stamped from the record with a kit-restamp receipt naming what was displaced. A transcript resumed with no record says so on the same receipt.

MCP command-line verbs and settings

mercury mcp manages MCP servers with the verbs add, import, list, get, remove, trust-reset and serve. The project's server definitions live in .mercury/mcp.json. The kit keys in settings govern selection and policy: kit.trustProjectServers approves project-defined servers without an individual approval card, kit.projectOn and kit.projectOff name the project servers approved or disabled in that settings source (an approval is written as name#digest, keyed to the server's definition as written; a bare name approves the current definition once and is rewritten in that form), and these three keys are read from your user and local settings only, so a checked-in project settings file cannot set them; kit.permit and kit.deny hold server policy entries, each naming exactly one of serverName, serverCommand or serverUrl, with denies taking precedence, and kit.managedOnly, when set by managed policy, uses only that policy's server allowlist.

Server definitions and environment

An environment placeholder in a server definition (the env:NAME form) shows as written in mercury mcp get, mercury mcp list and the /mcp cards. Hooks and MCP servers inherit your exported environment, minus provider keys, and never Mercury's own session variables. An MCP file loads its first 64 servers and says so; the MCP consent card opens on its single server's row.

Mercury as an MCP server

mercury mcp-server lets another agent submit outside reports, read session rows and search project memory. It uses Mercury's SDK and configured model accounts. Model calls spend the same account usage as other Mercury sessions. Start it from a project folder already trusted in Mercury.

See Mercury as an MCP server for client tokens, scope, stdio and HTTP.

Extensions · Hooks · Sessions · Saturn scheduling · Mercury as an MCP server