Hermes Switch UI — MCP Server Lifecycle

Discover → Install → Activate → Handshake → Available → Use · capability-gated page

CAPABILITY GATE MCP page requires gateway to report mcp or mcpFallback capability at startup probe. Missing → page shows backend-unavailable state. ① DISCOVER ② INSTALL ③ ACTIVATE ④ HANDSHAKE ⑤ AVAILABLE ⑥ USE Discover MCP Hub search + browse /api/mcp/hub-search — or — Manual Entry name · URL · cmd transport: http | stdio source: configured | preset Install Config written to ~/.hermes/ mcp_servers/ POST /api/mcp/configure or preset install POST /api/mcp/presets auth: bearer | oauth | none toolMode: all | include | exclude Activate Gateway loads config on restart or reload toggle via detail drawer PATCH /api/mcp/$name enabled: true → gateway spins up the server status: connected | failed | unknown Handshake MCP protocol negotiation list tools → list prompts → list resources → discoveredToolsCount populated Available status: connected tools appear in agent context GET /api/mcp server list + status GET /api/mcp/$name detail + logs Use agent invokes tool agent → tool call MCP server executes tool result → agent POST /api/mcp/test CAPABILITY GATING DETAIL mcp capability Full MCP runtime endpoints All actions available zero-fork / enhanced-fork mode gateway probed at startup mcpFallback capability Dashboard config only mcp_servers map exposed some actions limited portable / partial mode no mcp capability Page renders backend-unavailable state no server list shown disconnected / zero mode McpServer TYPE SHAPE (src/types/mcp.ts) id · name · enabled · transportType (http | stdio) authType (none | bearer | oauth) · toolMode (all | include | exclude) discoveredTools: McpDiscoveredTool[] · discoveredToolsCount status: connected | failed | unknown · lastTestedAt · lastError source: configured | preset · authEnvRef (env-reference for secrets) McpMaskedValue type — secrets never exposed to client ERROR / DISCONNECT PATHS Handshake fails → status: failed · lastError populated · server shown with red indicator in list Disconnect (toggle off) → gateway stops server · status: unknown · tools removed from agent context Test action → POST /api/mcp/test → McpTestResult { ok, latencyMs, discoveredTools, error } retry → back to Activate stage Stage color key cyan — UI-driven stages (Discover, Install, Activate) emerald — gateway/MCP protocol (Handshake, Available) violet — agent tool invocation (Use) Routes: /api/mcp (list) · /api/mcp/$name (detail) · /api/mcp/configure · /api/mcp/discover · /api/mcp/hub-search · /api/mcp/presets · /api/mcp/test · /api/mcp/$name.logs

Discover → Install → Activate

  • • Discover via MCP Hub search (/api/mcp/hub-search) or manual entry
  • • Install writes config to ~/.hermes/mcp_servers/
  • • POST /api/mcp/configure or preset install
  • • Activate: toggle in detail drawer → gateway spins server up
  • • auth: none | bearer | oauth · toolMode: all | include | exclude

Handshake → Available

  • • MCP protocol: list tools, list prompts, list resources
  • • discoveredToolsCount populated on success
  • • status: connected — tools appear in agent context
  • • GET /api/mcp — server list with status indicators
  • • Test via POST /api/mcp/test → latency + tool count

Use + Error Paths

  • • Agent calls tool → MCP server executes → result back to agent
  • • Handshake fail → status: failed · lastError set
  • • Disconnect toggle → tools removed from context
  • • Retry path: re-enable → back to Activate stage
  • • Secrets: McpMaskedValue — never sent to client

hermes-switchui · MCP Server Lifecycle · src/types/mcp.ts · src/routes/api/mcp/