mirror of
https://github.com/getpaseo/paseo.git
synced 2026-11-04 07:33:18 +00:00
Mohamed Boudra
a880c9619d
* feat(server): add background agents An agent can be created background in any workspace. It stays a durable, addressable agent, but default discovery, workspace status and attention leave it out. Effective background is agent.background || workspace.background. - Protocol: `create_agent_request.background` now marks the agent itself and stays the workspace intent for a workspace the request creates. Snapshots carry `background`. The daemon advertises `features.backgroundAgents`. Clients advertise the `background_agents` capability. - Daemon: the flag persists in the agent record, so restart and resume keep it. AgentDirectory owns visibility. Inclusive reads and subscriptions from sources without `background_agents` see only agents in background workspaces, because older apps would otherwise open a tab for each one. - Inheritance: omitted on agent-scoped creation, children and new workspaces take the caller agent's background. - MCP: create_agent accepts `background`. - SDK: placing a background agent in an existing workspace, or under a caller, fails fast with "Update the host to use background agents." on older hosts. - CLI: `ls -a` and `ls --background` add a BACKGROUND column. * feat(app): hide background agents from tabs, track and status * docs(plugins): point hidden helpers at background agents * fix: keep background agents hidden across cache reload and connected hosts * fix: keep remote creation working on older hosts and inherit foreign parents' background
204 lines
16 KiB
Markdown
204 lines
16 KiB
Markdown
---
|
||
title: MCP reference
|
||
description: Reference for the Paseo tools agents use to manage agents, workspaces, scripts, terminals, and schedules.
|
||
nav: MCP reference
|
||
order: 34
|
||
category: Orchestration
|
||
---
|
||
|
||
# MCP reference
|
||
|
||
[Enable Paseo tools](/docs/orchestration#get-started) 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:
|
||
|
||
```json
|
||
{
|
||
"$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. `background: true` hides it from tabs, default lists, your subagent track and notifications; you still get its finish notification. Omission inherits your own value. |
|
||
| `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](/docs/worktrees#scripts-and-services) 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.
|
||
|
||
New-agent run workspaces are archived when each run ends by default. `create_schedule` and `update_schedule` do not expose **Archive on finish** (`archiveOnFinish`); [change the option in the app](/docs/schedules#keep-run-workspaces) to keep subsequent run workspaces active.
|
||
|
||
### 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](/docs/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](/docs/browser-tools).
|
||
|
||
### Voice
|
||
|
||
| Tool | Function |
|
||
| ------- | ----------------------------------------------------------------------------------------- |
|
||
| `speak` | Speak text through daemon-managed voice output. Available only in voice-enabled sessions. |
|