Skip to content

Switchyard MCP

Switchyard's MCP server lets agents discover local runtime state without scraping terminals, guessing ports, or reading stale logs.

It is a dependency-free stdio server:

switchyard mcp

The server speaks newline-delimited JSON-RPC over stdin/stdout and exposes tools for runtime discovery, logs, and process control. When launched from a project or any child directory, it automatically pins the server root to the nearest switchyard.toml; no absolute project path argument is needed in the normal path. When launched from a Switchyard-registered worktree, the server keeps the parent project as the allowed root and uses the worktree as the default request cwd, so switchyard://project/brief is branch-scoped immediately.

Codex

Codex reads MCP server configuration from ~/.codex/config.toml. From inside the Switchyard project, install the server directly:

switchyard mcp install

This detects the project root and writes the full MCP server block to your Codex config. The project path is stored in Switchyard's local state as a project alias; the generated config always carries that alias in --project:

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

If no switchyard executable is visible, the helper prints a commented fallback that launches the current Python interpreter with args = ["-m", "switchyard", "mcp", "--project", "name"]. The generated block does not contain cwd, --cwd, or an absolute project path. If SWITCHYARD_HOME is set during setup, the generated block includes an [mcp_servers.name.env] table so Codex launches the server with the same local alias state.

To inspect the config first, generate ready-to-paste setup text:

switchyard mcp config
switchyard mcp config --json

The helper registers the local project alias and prints the same path-free TOML. Use --json for machine-readable setup details, including the generated TOML, launch command, alias registration state, and ok: false setup errors. Use --name for multiple projects:

switchyard mcp install --name switchyard-entropic
switchyard mcp config --name switchyard-entropic

Switchyard refuses to repoint an existing alias at a different project unless you pass --force.

List registered aliases from anywhere:

switchyard mcp projects --json

The JSON includes home and state_path, which lets agents confirm the exact local Switchyard registry used for alias lookup.

To verify the full path-free setup loop from a configured project:

switchyard mcp smoke --json

The smoke uses temporary Switchyard/Codex homes, checks generated config for project paths, confirms dry runs do not register aliases, installs a real Codex block, and launches the configured MCP command from a neutral directory.

Resources

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

  • switchyard://project/brief: configured_services, compact runtime state, service URLs, checkout state, changed files, env_warnings, and recent errors.
  • switchyard://project/doctor: project setup, proxy config, services, and env_warnings.
  • switchyard://agent/guide: short agent workflow guide.

Project resources use the server root detected by switchyard mcp or resolved from --project <name>. Reading resources does not initialize Switchyard state.

Prompts

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

  • switchyard_runtime_handoff: starts an agent session with the brief, doctor, focused service lookup, and approval boundaries.
  • switchyard_branch_runtime: accepts branch and optional services arguments and guides an agent through worktree creation and service startup.

Prompts are read-only templates. They do not create worktrees, start services, or write Switchyard state.

Tools

  • switchyard_doctor: project config, proxy, services, Switchyard version, and env_warnings for missing configured env link/copy sources.
  • switchyard_create: create a managed git worktree and sync configured env files.
  • switchyard_list: registered Switchyard worktrees for the project.
  • switchyard_status: registered services with running/stale state.
  • switchyard_brief: compact project/runtime summary, including configured services, running service state, checkout, changed-file, env_warnings, and recent-error state.
  • switchyard_where: URL, port, PID, worktree, and log path for one service.
  • switchyard_logs: recent log tail for one service or branch.
  • switchyard_up: start local services for a branch/worktree.
  • switchyard_checkout: map a branch runtime back to configured canonical ports.
  • switchyard_uncheckout: stop canonical port mappings.
  • switchyard_down: stop Switchyard-managed services.

Recommended agent flow:

  1. Read switchyard://project/brief, or call switchyard_brief when resources are unavailable.
  2. Use configured_services and configured_profiles before choosing service names, and check env_warnings before creating worktrees.
  3. Use switchyard_runtime_handoff when the client exposes prompts and wants a ready-made starter workflow.
  4. Call switchyard_where for one service.
  5. Call switchyard_logs for focused debugging.
  6. Call switchyard_create when the user wants a new branch runtime.
  7. Call switchyard_up, switchyard_checkout, switchyard_uncheckout, or switchyard_down only when the user wants runtime changes.

Tool Annotations

Switchyard includes MCP tool annotations for safer clients:

  • Discovery tools such as switchyard_brief, switchyard_where, and switchyard_logs are marked read-only and closed-world.
  • switchyard_up is marked as a potentially destructive/open-world mutation because it executes configured project commands.
  • switchyard_checkout is marked as a local, non-destructive mutation because it starts Switchyard-managed port forwarders.
  • switchyard_create, switchyard_uncheckout, and switchyard_down are marked local destructive mutations because they create filesystem/git state or stop local runtime state.

Structured Output

Every tool advertises an MCP outputSchema and returns JSON structuredContent with an object envelope. For example, switchyard_status returns { "services": [...] } and switchyard_logs returns { "logs": [...] }, so agents can read tool results without scraping text.

Safety

  • The MCP server is local stdio, not a network listener.
  • switchyard mcp install and switchyard mcp config register one local project alias for the detected root; tool calls cannot jump to a different local repository.
  • switchyard_create creates a local git worktree and syncs configured env files.
  • switchyard_up starts local processes from switchyard.toml.
  • switchyard_checkout starts local canonical-port forwarders.
  • switchyard_uncheckout stops Switchyard-managed canonical-port forwarders.
  • switchyard_down stops Switchyard-managed PIDs.
  • When called from a registered worktree cwd, switchyard_uncheckout and switchyard_down default to that worktree's branch. From the project root, an omitted branch still means all matching Switchyard-managed runtime state.
  • Keep client approval enabled for write/action tools.
  • Run setup from the checkout you are configuring; --cwd remains a hidden compatibility escape hatch for older automation, not the normal setup path.
  • Use --project <name> when an MCP client starts the server outside the project tree.
  • Use switchyard mcp projects --json to inspect local alias registrations, confirm the home/state_path, and spot stale project paths.