paseo/public-docs/mcp.md

title, description, nav, order, category

title	description	nav	order	category
MCP reference	Reference for the Paseo tools agents use to manage agents, workspaces, scripts, terminals, and schedules.	MCP reference	34	Orchestration

MCP reference

Enable Paseo tools to give agents this catalog. Ask for an outcome in natural language, or use the tool interfaces below.

Configuration

Setting	Default	Purpose
daemon.mcp.enabled	true	Run the MCP server.
daemon.mcp.injectIntoAgents	false	Give agents launched by Paseo access to its tools.

Depending on the provider, Paseo delivers tools through its native tool interface or MCP. The capabilities are the same. Start a new agent or reload an existing one after changing injection settings.

Limit Paseo tools by provider

Use provider policies when different agent profiles should receive different Paseo tools. Enable tool injection globally, then add paseoTools to the exact provider IDs you launch:

{
  "$schema": "https://paseo.sh/schemas/paseo.config.v1.json",
  "version": 1,
  "daemon": {
    "mcp": {
      "enabled": true,
      "injectIntoAgents": true
    }
  },
  "agents": {
    "providers": {
      "codex-lead": {
        "extends": "codex",
        "label": "Codex Lead"
      },
      "codex-worker": {
        "extends": "codex",
        "label": "Codex Worker",
        "paseoTools": {
          "disabledTools": ["create_agent", "send_agent_prompt", "kill_agent"]
        }
      },
      "codex-isolated": {
        "extends": "codex",
        "label": "Codex Isolated",
        "paseoTools": {
          "enabled": false
        }
      }
    }
  }
}

Run paseo reload after editing ~/.paseo/config.json, then start a new agent or reload an existing one. A running session keeps the catalog it received at launch.

Omitting paseoTools enables the complete catalog. Set enabled to false to remove the catalog, or list exact tool IDs in disabledTools to remove selected tools. Custom profiles do not inherit this policy from extends; configure each custom provider ID separately.

Browser tools still require browser tools to be enabled and a connected browser host. The voice-only speak tool is separate from this policy.

This setting limits the catalog presented to an agent. It is not a security boundary for an agent that can access the host through a shell.

Mental model

Workspaces decide where work happens; agent parentage decides who owns the work.

• An agent that calls create_agent without a workspaceId gets a subagent in its own workspace.
• Passing a workspaceId places that subagent in another workspace without detaching it from its parent.
• A top-level MCP caller without a workspace gets a new local workspace.
• Create a workspace first when you need worktree isolation, a specific branch, or a pull request checkout.

MCP does not expose an agent-detach tool. Detaching is a manual user action in the app or CLI.

Tools

Agents

Tool	Function
create_agent	Create an agent, optionally placing it in an existing workspace with workspaceId. Use initialPrompt to start work; returns without waiting for completion.
send_agent_prompt	Send a prompt using agentId and prompt; returns without waiting for completion.
get_agent_status	Return the latest snapshot for an agent.
list_agents	List recent agents as compact metadata; includeBackground: true includes background work.
cancel_agent	Abort an agent's current run but keep the agent alive.
archive_agent	Soft-delete an agent and remove it from the active list.
kill_agent	Terminate an agent session permanently.
update_agent	Update an agent name, labels, or runtime settings such as mode/model/thinking/features.
get_agent_activity	Return recent agent timeline entries as a curated summary.
set_agent_mode	Switch an agent's session mode.

Paseo agents receive finish, error, and permission notifications by default; set notifyOnFinish: false to disable them. External MCP clients use get_agent_status and get_agent_activity to check results.

Workspaces

Tool	Function
create_workspace	Create a local or worktree-isolated workspace. Worktrees can branch off, check out a branch, or a PR. background: true hides it from default lists and the sidebar while preserving history and access by ID. Omission inherits the calling agent’s workspace setting, or defaults to false without a caller.
list_workspaces	List active workspaces and their directories and isolation. Use includeBackground: true to include background workspaces.
rename_workspace	Change the user-visible name of the current or specified workspace.
archive_workspace	Archive a workspace and the sessions it owns.

For worktree isolation, create_workspace accepts the same useful choices as the app: branch off from a base, check out an existing branch, or check out a pull request. The worktree remains an implementation detail of the workspace lifecycle.

Workspace scripts

These tools manage scripts configured in a workspace's paseo.json. Each requires an explicit workspaceId; start and stop also require the configured scriptName.

Tool	Function
list_workspace_scripts	List configured scripts with lifecycle, terminal, port, proxy URL, and health metadata.
start_workspace_script	Start a configured script through Paseo's managed launcher.
stop_workspace_script	Stop a running script through its supervised terminal.

See Git worktrees for paseo.json configuration.

Terminals

Tool	Function
list_terminals	List terminal sessions for one working directory or all working directories.
create_terminal	Create a terminal session for a working directory.
kill_terminal	Kill a terminal session.
capture_terminal	Capture plain-text output from a terminal session.
send_terminal_keys	Send text or special key tokens to a terminal session.

Schedules and heartbeats

Both use the same cron engine, but they have deliberately different interfaces.

Tool	Function
create_schedule	Create a cron schedule that starts a new agent for each run.
list_schedules	List new-agent schedules managed by the daemon.
inspect_schedule	Inspect a schedule and its run history.
pause_schedule	Pause an active schedule.
resume_schedule	Resume a paused schedule.
update_schedule	Change a schedule's cron, prompt, agent settings, limits, or other settings.
schedule_logs	Return recent runs and output for a schedule.
run_schedule_once	Start one new-agent schedule run without changing its cron.
delete_schedule	Delete a new-agent schedule permanently.
create_heartbeat	Send a recurring cron-backed prompt into the current agent.
delete_heartbeat	Delete one of the current agent's heartbeats.

MCP heartbeats are ephemeral: create or delete them. To change one, delete it and create a replacement. Pause, resume, update, inspect, logs, and run-once apply to new-agent schedules only.

Agent profiles

Tool	Function
list_profiles	Return the host's saved agent profiles, including their notes and launch settings. Returns an empty list when none are configured.

Before delegating, read each profile's notes and choose the profile the user named or the one that fits the task. See Agent profiles for setup and example notes.

create_agent has no profile parameter and requires a provider/model pair. If the profile has no model, call list_models for its provider and choose an available model for the task before launching. Apply the chosen profile's values to the launch request:

Profile field	create_agent field
provider and optional model	provider as provider/model, using the saved or discovered model ID
modeId	settings.modeId
thinkingOptionId	settings.thinkingOptionId
featureValues	settings.features
notes	Selection guidance for the orchestrator; supply the task in initialPrompt

Omit absent optional settings. If no profile fits, use provider discovery to choose available settings.

Providers

Tool	Function
list_providers	List configured agent providers, availability, and modes.
list_models	List models for an agent provider.
inspect_provider	Inspect compact provider capabilities and draft feature settings.

Permissions

Tool	Function
list_pending_permissions	Return pending permission requests across agents.
respond_to_permission	Approve or deny a pending permission request.

Browser

Browser automation is opt-in and adds tools for opening tabs, reading pages, clicking, typing, and taking screenshots. See the Browser tools reference.

Voice

Tool	Function
speak	Speak text through daemon-managed voice output. Available only in voice-enabled sessions.