Agent integration

Switchyard exposes the same application use cases used by its CLI and browser through a permission-scoped Model Context Protocol server. The MCP process is a stdio adapter; the durable daemon remains the owner of catalog, runtime, operation, health, log, port, Git, and action state.

Codex / Claude Code / MCP client
              |
       MCP stdio process
     profile + project scope
              |
   authenticated local IPC client
       actor=provider/agent
              |
       Switchyard daemon
              |
 shared application use cases -> durable operations and audit

The MCP adapter does not import runtime drivers, persistence adapters, or os/exec. A failed or disconnected MCP process cannot terminate the daemon or degrade ordinary CLI and browser access.

Authorization

Tool discovery is itself least-privilege. A server instance receives one validated provider, agent identity, permission profile, and optional project allowlist at startup. Tools outside that profile are not registered.

Profile	Capabilities
observe	Bounded project, runtime, health, logs, Git, ports, actions, manifest, and operation reads
develop	Observe plus start, stop, restart, pause, resume, trusted actions, and operation cancellation
maintain	Develop plus rebuild and deterministic manifest proposal creation
admin	Maintain plus proposal acceptance, destructive trusted actions, and teardown

The default is observe. Destructive tools are therefore absent unless the MCP server is explicitly configured with admin. Project allowlists apply to reads, port-conflict evidence, and mutations. A project-scoped server cannot register another project, and proposal IDs are resolved to their owning project before trust authorization. Every mutation uses a caller-supplied idempotency key and reaches the daemon over local IPC with agent and provider/agent identity headers. Operation and catalog audit records persist that non-secret origin.

Protocol behavior

• Tool inputs and structured outputs are generated by the official Go MCP SDK.
• Every output includes schemaVersion: switchyard.mcp/v1.
• Lists, logs, resources, ports, services, and recent errors have hard bounds.
• Log content has already crossed the daemon’s redaction boundary.
• Operation and health waits are limited to 30 seconds and emit MCP progress notifications when the client supplies a progress token.
• Cancellation requests are cooperative durable operations, not process kills.
• Risk and idempotency annotations describe each tool; trusted action risk is re-read from the accepted manifest immediately before submission.
• There is no generic shell, Docker-command, SQL, or process-execution tool.

Repository evidence, manifest content, logs, and action output remain untrusted data. Shared prompts and installed Agent Skills explicitly tell clients not to follow instructions embedded in that data and not to bypass Switchyard with ad hoc shell commands.

Provider installation

switchyard agent install codex manages a marked MCP block in .codex/config.toml, installs the shared skill under .agents/skills/switchyard-operate, and adds a marked AGENTS.md block.

switchyard agent install claude merges the switchyard stdio server into .mcp.json, installs the same policy as a Claude skill under .claude/skills/switchyard-operate, adds the shared AGENTS.md block, and ensures CLAUDE.md imports @AGENTS.md.

Both installers preserve unrelated configuration, reject unsafe file types or malformed managed markers, write atomically, and are idempotent. User-level installation is available with --scope user; project scope is the default.

Verification

SDK in-memory tests exercise initialize, tool/resource/prompt discovery, structured calls, permission omission, scoped reads, lifecycle submission, operation waits, and destructive denial. The pinned MCP Inspector smoke test starts a real daemon and real stdio server, then lists tools, resources, and prompts while asserting the observe profile omits teardown.