How Agents Use Switchyard

Switchyard is designed so agents do not need to infer local runtime state from terminal scrollback.

MCP Server

Run Switchyard as a local stdio MCP server:

switchyard mcp

When launched from a project or any child directory, switchyard mcp resolves the nearest switchyard.toml automatically. Avoid hard-coded project path args in normal MCP setup. When launched from a Switchyard-registered worktree, MCP resources and tools use the parent project config and default to that worktree's branch.

For Codex, generate project-specific setup text from inside the repository:

switchyard mcp install
switchyard mcp config

switchyard mcp install detects the root and writes the full server block to ~/.codex/config.toml. switchyard mcp config prints a trusted config snippet using a local project alias:

args = ["mcp", "--project", "name"]

If no switchyard executable is visible, the snippet falls back to the current Python interpreter with args = ["-m", "switchyard", "mcp", "--project", "name"]. The alias keeps MCP client setup free of hand-written project paths. Generated Codex config should not contain cwd, --cwd, or an absolute project path. It uses [mcp_servers.name.env] to preserve an explicit SWITCHYARD_HOME from setup. Use switchyard mcp config --json or switchyard mcp install --dry-run --json when an agent needs machine-readable setup details or a setup error envelope. Use switchyard mcp projects --json to inspect registered aliases and confirm the local home/state_path used for alias lookup. Use switchyard mcp smoke --json from a configured project to verify the full path-free setup loop with temporary local state.

Clients that support MCP resources can read stable, read-only context before choosing a tool:

switchyard://project/brief
switchyard://project/doctor
switchyard://agent/guide

Reading these resources does not initialize Switchyard state.

Clients that support MCP prompts can expose ready-made workflows:

switchyard_runtime_handoff
switchyard_branch_runtime

Prompts are read-only templates. Runtime changes still happen only through the mutation tools.

Codex Skill

Install the bundled skill when an agent benefits from Switchyard-specific workflow guidance:

switchyard skill install

Available MCP tools:

switchyard_doctor
switchyard_create
switchyard_list
switchyard_status
switchyard_brief
switchyard_where
switchyard_logs
switchyard_up
switchyard_checkout
switchyard_uncheckout
switchyard_down

Read switchyard://project/brief before reading logs or guessing URLs. If MCP resources are unavailable, call switchyard_brief. Treat switchyard_create, switchyard_up, switchyard_checkout, switchyard_uncheckout, and switchyard_down as visible local actions because they create worktrees, start services, or change port mappings. When MCP switchyard_uncheckout or switchyard_down runs with a registered worktree cwd, an omitted branch means that worktree's branch. From the project root, an omitted branch still means all matching Switchyard-managed runtime state.

Best Commands For Agents

Use:

switchyard init --dry-run --json
switchyard doctor --json
switchyard list --json

When checking setup, previewing first-run config, or reporting why a project is not initialized. doctor --json includes detailed env_warnings for missing configured env link/copy sources.

Use:

switchyard brief --json

For a compact overview. When run inside a Switchyard-registered worktree, the CLI uses that worktree's branch and parent project automatically:

{
  "project": "entropic",
  "branch": "feature/login",
  "configured_services": ["api", "web"],
  "services": [
    {
      "service": "web",
      "status": "running",
      "url": "http://web.feature-login.entropic.localhost:7331",
      "port": 41000,
      "log_file": "/Users/me/.switchyard/logs/entropic/feature-login/web.log"
    }
  ],
  "checkouts": [
    {
      "service": "web",
      "status": "running",
      "listen_host": "127.0.0.1",
      "listen_port": 3000,
      "target_host": "127.0.0.1",
      "target_port": 41000
    }
  ],
  "changed_files": [" M src/app.tsx"],
  "env_warnings": [],
  "recent_errors": []
}

switchyard brief --json and switchyard://project/brief also include configured_services and env_warnings, so agents can discover valid service names and see missing env sources in the first compact state read.

Use:

switchyard where web feature/login --json

When you need one service.

Use:

switchyard logs web --branch feature/login -n 120 --json

When debugging.

Log JSON returns each selected service with service, branch, log_file, and an array of tail lines.

Use action JSON when a shell-only agent needs to report what it changed:

switchyard up feature/login web --json
switchyard checkout feature/login web --json
switchyard down --branch feature/login web --json

Action JSON returns ok, action, requested services, messages, and a JSON error envelope on failure.

When down or uncheckout run inside a registered worktree without an explicit branch, Switchyard scopes the action to that worktree's branch. From the project root, omitting the branch still means all matching Switchyard state.

MCP clients can also read tool annotations: discovery tools are read-only, switchyard_up is conservative because it runs configured project commands, and worktree/process/checkout tools are marked as mutations.

Token-Saving Workflow

Instead of repeatedly running:

git status
lsof -i
ps
cat on logs
package manager inspection
browser URL guessing

Prefer:

switchyard brief --json

Then inspect only the log file or service that looks relevant.

Stable Env Vars

Each service receives:

SWITCHYARD=1
SWITCHYARD_PROJECT
SWITCHYARD_PROJECT_SLUG
SWITCHYARD_BRANCH
SWITCHYARD_BRANCH_SLUG
SWITCHYARD_SERVICE
SWITCHYARD_PORT
SWITCHYARD_URL

For peer services:

SWITCHYARD_WEB_URL
SWITCHYARD_WEB_PORT
SWITCHYARD_API_URL
SWITCHYARD_API_PORT

Service commands can also use peer placeholders such as {web_url}, {web_port}, {api_url}, and {api_port}. For hyphenated service names, use underscores in placeholders, such as {db_main_port}.

MCP Tool Order

Read switchyard://project/brief, or call switchyard_brief when resources are unavailable
Use switchyard_runtime_handoff when prompts are available and a starter workflow helps
switchyard_where for a specific service
switchyard_logs only for the service that looks relevant
switchyard_create when the user asked for a missing branch runtime
switchyard_up, switchyard_checkout, switchyard_uncheckout, or switchyard_down only when the user asked for runtime changes