agentHost: MCP support

CHANGELOG.md

@@ -27,6 +27,42 @@ changes accumulate. Track in-flight protocol changes via PRs touching
 
 Spec version: `0.3.0`
 
+### Added
+
+- `McpServerCustomization` now models MCP servers as first-class session
+  customizations: `enabled`, `runtimeStatus` (a discriminated
+  `McpServerStatus` union covering `starting`, `ready`, `authRequired`,
+  `error`, `stopped`), an optional `channel` URI for an `mcp://`
+  side-channel into the upstream server, and an optional `mcpApp` block
+  carrying `AhpMcpUiHostCapabilities` so clients can render
+  [MCP Apps](https://github.com/modelcontextprotocol/ext-apps).
+- `McpServerStatusAuthRequired` carries `ProtectedResourceMetadata` plus
+  `reason` / `requiredScopes` / `description`, letting clients drive the
+  existing `authenticate` command for per-MCP-server auth challenges.
+- `Customization` now includes `McpServerCustomization` at the top level
+  (hosts MAY surface globally-configured MCP servers directly rather
+  than only inside a plugin or directory). MCP servers remain valid as
+  children of a container.
+- New `session/mcpServerStatusChanged` action — narrow upsert of
+  `runtimeStatus` + `channel` on an existing `McpServerCustomization`
+  by id, intended for the high-frequency
+  `starting`/`ready`/`authRequired` transitions. Other customization
+  fields stay in `session/customizationUpdated` territory.
+- `InitializeParams.capabilities` — optional client-capability bag
+  declared during the handshake. First entry is `mcpApps?: {}`; hosts
+  SHOULD only populate `McpServerCustomization.mcpApp` / `channel` for
+  clients that declared it.
+- New guide page `docs/guide/mcp.md` (with an MCP Apps subsection) and
+  new spec page `docs/specification/mcp-channel.md`.
+
+### Changed
+
+- Replaced `ToolCallBase.toolClientId?: string` with a discriminated
+  `ToolCallBase.contributor?: ToolCallContributor` union
+  (`ToolCallClientContributor` / `ToolCallMcpContributor`) so MCP-served
+  tool calls can be attributed back to their originating
+  `McpServerCustomization`. `session/toolCallStart` carries the new
+  `contributor?` field in place of `toolClientId?`.
 - Renamed the `UserMessage` type to `Message` and surfaced it consistently
   across turn state (`Turn.message`, `ActiveTurn.message`, `PendingMessage.message`)
   and the actions that carry it (`session/turnStarted`,

docs/.vitepress/config.mts

@@ -36,6 +36,7 @@ export default withMermaid(defineConfig({
             { text: 'Elicitation', link: '/guide/elicitation' },
             { text: 'Terminals', link: '/guide/terminals' },
             { text: 'Customizations', link: '/guide/customizations' },
+            { text: 'MCP Servers', link: '/guide/mcp' },
             { text: 'Write-Ahead Reconciliation', link: '/guide/reconciliation' },
           ],
         },
@@ -57,6 +58,7 @@ export default withMermaid(defineConfig({
             { text: 'Lifecycle', link: '/specification/lifecycle' },
             { text: 'Channels & Subscriptions', link: '/specification/subscriptions' },
             { text: 'Authentication', link: '/specification/authentication' },
+            { text: 'MCP Channel', link: '/specification/mcp-channel' },
             { text: 'Versioning', link: '/specification/versioning' },
           ],
         },

docs/guide/customizations.md

@@ -1,11 +1,13 @@
 # Customizations
 
-Customizations extend agent sessions with additional capabilities — agents, skills, prompts, rules, hooks, and MCP servers. AHP organises them as a discriminated union with a fixed set of types and a strict two-level tree:
+Customizations extend agent sessions with additional capabilities — agents, skills, prompts, rules, hooks, and MCP servers. AHP organises them as a discriminated union with a fixed set of types and a shallow tree:
 
-- **Top-level entries are always containers**: a `PluginCustomization` (an [Open Plugins](https://open-plugins.com/) package) or a `DirectoryCustomization` (a directory the host watches on disk).
-- **Everything else is a child** of a container: `AgentCustomization`, `SkillCustomization`, `PromptCustomization`, `RuleCustomization`, `HookCustomization`, `McpServerCustomization`.
+- **Top-level entries are typically containers**: a `PluginCustomization` (an [Open Plugins](https://open-plugins.com/) package) or a `DirectoryCustomization` (a directory the host watches on disk). The host MAY also surface a bare `McpServerCustomization` at the top level (for example, a globally-configured MCP server that isn't bundled in a plugin).
+- **Other children live inside a container**: `AgentCustomization`, `SkillCustomization`, `PromptCustomization`, `RuleCustomization`, `HookCustomization`, `McpServerCustomization`. MCP servers can therefore appear in either position.
 
-The agent host is authoritative on the effective tree. Clients publish plugins, the host expands them into children, and the host owns disk-backed directories.
+The agent host is authoritative on the effective tree. Clients publish plugins, the host expands them into children, and the host owns disk-backed directories and bare top-level MCP servers.
+
+For MCP-specific behaviour (server lifecycle, authentication, App support), see [MCP Servers](/guide/mcp).
 
 ## Sources
 
@@ -112,10 +114,10 @@ SkillCustomization        { type: 'skill';       description?, disableModelInvoc
 PromptCustomization       { type: 'prompt';      description? }
 RuleCustomization         { type: 'rule';        description?, alwaysApply?, globs? }    // covers "instruction" formats too
 HookCustomization         { type: 'hook';        event?, matcher? }
-McpServerCustomization    { type: 'mcpServer';   description? }
+McpServerCustomization    { type: 'mcpServer';   enabled, runtimeStatus, channel?, mcpApp? }   // see /guide/mcp
 ```
 
-The protocol intentionally omits host-internal execution details (a hook's command/script, an MCP server's `command`/`args`/`env`, etc.). Those stay on the agent host; clients see only what's needed for display, search, and selection. MCP tools and their descriptions surface through the standard tool channels once the server is running.
+The protocol intentionally omits host-internal execution details (a hook's command/script, an MCP server's `command`/`args`/`env`, etc.). Those stay on the agent host; clients see only what's needed for display, search, and selection. MCP tools and their descriptions surface through the standard tool channels once the server is running. The MCP-specific runtime fields (`runtimeStatus`, `channel`, `mcpApp`) are covered in [MCP Servers](/guide/mcp).
 
 Consumers filter by `type` to find the children they care about — for example, the agent picker reads every `AgentCustomization` under any container: