MCP Protocol Handshake

How the Hermes Agent establishes a session with an MCP server — initialize through tool invocation

Switch UI status indicator Hermes Agent MCP host • port 8642 MCP Server stdio or HTTP transport spawn init caps tools prompts resources indexed chat result 1. Spawn / connect to server stdio: fork process • HTTP: open connection 2. initialize request protocolVersion, clientInfo, client capabilities 3. initialize response serverInfo, server capabilities (tools, prompts, resources) 4. tools/list enumerate available tools tools/list response array of tool definitions (name, description, inputSchema) 5. prompts/list enumerate available prompts prompts/list response array of prompt templates 6. resources/list enumerate available resources resources/list response array of resource URIs 7. Index capabilities tools + prompts + resources now available in chat Status → Connected UI indicator updates 8. tools/call (on chat turn) toolName, arguments — agent decided to use this tool tools/call result content array returned to agent context Error path server fails to start / handshake timeout → agent marks server unavailable → UI shows Disconnected / error log check env vars and command path Transport emerald = Agent → Server (request) violet = Server → Agent (response) cyan = Agent → Switch UI (status)

Handshake phase

  • • Agent spawns (stdio) or connects (HTTP) to the server
  • • initialize exchange negotiates protocol version and capabilities
  • • Agent then calls tools/list, prompts/list, resources/list
  • • All capabilities indexed in-memory — available immediately in chat

Tool invocation

  • • During a chat turn the agent decides which tool to call
  • • Sends tools/call with tool name and arguments
  • • Server executes the tool and returns a content array
  • • Result injected back into agent context for the response

Failure modes

  • • Server fails to start → check command path and dependencies
  • • Handshake timeout → server may be slow or unreachable
  • • Missing env var → credentials not in ~/.hermes/.env
  • • Agent marks server unavailable; UI shows Disconnected

Hermes Switch UI • MCP protocol handshake • spawn → initialize → capability lists → tools/call