# Agent integration

> Provider-neutral MCP, permission, audit, guidance, and agent-session architecture.

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.

```text
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.