Code Execution and MCP Tools

Relevant source files

• apps/desktop/src/lib/mcp-dashboard-oauth.test.ts
• apps/desktop/src/lib/mcp-dashboard-oauth.ts
• hermes_cli/mcp_config.py
• hermes_cli/subcommands/mcp.py
• tests/gateway/test_internal_event_bypass_pairing.py
• tests/hermes_cli/test_apply_profile_override.py
• tests/hermes_cli/test_auth_toctou_file_modes.py
• tests/hermes_cli/test_mcp_add_command_dest.py
• tests/hermes_cli/test_mcp_config.py
• tests/hermes_cli/test_mcp_dashboard_oauth.py
• tests/run_agent/test_24996_fallback_exhaustion_cooldown.py
• tests/tools/test_approved_command_clean_slate.py
• tests/tools/test_browser_orphan_reaper.py
• tests/tools/test_code_execution.py
• tests/tools/test_code_execution_windows_env.py
• tests/tools/test_file_tools_live.py
• tests/tools/test_interrupt.py
• tests/tools/test_local_env_blocklist.py
• tests/tools/test_local_env_cwd_recovery.py
• tests/tools/test_local_env_windows_msys.py
• tests/tools/test_mcp_circuit_breaker.py
• tests/tools/test_mcp_client_cert.py
• tests/tools/test_mcp_dashboard_oauth.py
• tests/tools/test_mcp_oauth.py
• tests/tools/test_mcp_oauth_integration.py
• tests/tools/test_mcp_oauth_manager.py
• tests/tools/test_mcp_preflight_content_type.py
• tests/tools/test_mcp_probe.py
• tests/tools/test_mcp_reconnect_signal.py
• tests/tools/test_mcp_stability.py
• tests/tools/test_mcp_tool.py
• tests/tools/test_mcp_tool_401_handling.py
• tests/tools/test_mcp_tool_session_expired.py
• tests/tools/test_notify_on_complete.py
• tests/tools/test_process_registry.py
• tests/tools/test_tirith_security.py
• tests/tools/test_voice_cli_integration.py
• tests/tools/test_voice_mode.py
• tests/tools/test_watch_patterns.py
• tools/code_execution_tool.py
• tools/environments/local.py
• tools/interrupt.py
• tools/mcp_dashboard_oauth.py
• tools/mcp_oauth.py
• tools/mcp_oauth_manager.py
• tools/mcp_tool.py
• tools/process_registry.py
• tools/tirith_security.py
• tools/voice_mode.py
• web/src/lib/mcp-dashboard-oauth.test.ts
• web/src/lib/mcp-dashboard-oauth.ts
• website/docs/reference/mcp-config-reference.md
• website/docs/user-guide/features/mcp.md

The Hermes Agent framework provides advanced capabilities for programmatic tool interaction and external tool discovery. This is achieved through two primary mechanisms: the Code Execution Sandbox for programmatic tool calling (PTC) and the Model Context Protocol (MCP) for integrating external tool servers.

1. Code Execution Sandbox (Programmatic Tool Calling)

The code execution sandbox enables the LLM to write Python scripts that call Hermes tools programmatically via RPC, collapsing multi-step tool chains into a single inference turn. This reduces context window usage by preventing intermediate tool results from entering the conversation history. tools/code_execution_tool.py3-7

1.1 Architecture and Data Flow

The execute_code tool allows the LLM to generate a Python script that calls whitelisted tools through an RPC bridge. Only the script's stdout is returned to the LLM—intermediate tool results never enter the context window. The system supports two transports: Local (UDS/TCP) and Remote (File-based) for environments like Docker or SSH. tools/code_execution_tool.py8-29

Programmatic Tool Calling (PTC) Flow

Sources: tools/code_execution_tool.py8-29 tools/code_execution_tool.py10-25

1.2 Tool Stub Generation

The generate_hermes_tools_module function builds the source code for a hermes_tools.py module. This module contains stubs that map Python function calls to JSON-RPC requests. tools/code_execution_tool.py43-49

The sandbox supports a specific subset of tools defined in SANDBOX_ALLOWED_TOOLS:

• web_search, web_extract
• read_file, write_file, search_files, patch
• terminal

Sources: tools/code_execution_tool.py61-70 tests/tools/test_code_execution.py84-118

1.3 Security and Resource Limits

The sandbox enforces several security boundaries and resource constraints:

• Platform Support: Available on Linux and macOS via Unix domain sockets. On Windows, the system falls back to loopback TCP for the sandbox RPC transport. tools/code_execution_tool.py27-29 tools/code_execution_tool.py51-54
• Timeout: Default execution limit of 300 seconds (DEFAULT_TIMEOUT). tools/code_execution_tool.py73
• Call Volume: Default maximum of 50 tool calls per script execution (DEFAULT_MAX_TOOL_CALLS). tools/code_execution_tool.py74
• Output Capping: Stdout is capped at 50 KB (MAX_STDOUT_BYTES) and Stderr at 10 KB (MAX_STDERR_BYTES). tools/code_execution_tool.py75-76
• Environment Scrubbing: The _scrub_child_env function removes sensitive variables (keys, tokens, passwords) using _SECRET_SUBSTRINGS and _SAFE_ENV_PREFIXES while preserving operational variables in _HERMES_CHILD_ALLOWED and OS-essential variables like SYSTEMROOT on Windows. tools/code_execution_tool.py133-143 tools/code_execution_tool.py145-158 tools/code_execution_tool.py164-169 tools/code_execution_tool.py177-183

Sources: tools/code_execution_tool.py51-54 tools/code_execution_tool.py72-76 tools/code_execution_tool.py145-183

---

2. Model Context Protocol (MCP) Integration

Hermes Agent supports the Model Context Protocol (MCP), allowing it to connect to external tool servers (e.g., GitHub, Filesystem) and register their capabilities dynamically. tools/mcp_tool.py3-11 Configuration for MCP servers is read from ~/.hermes/config.yaml under the mcp_servers key. tools/mcp_tool.py15-52

2.1 MCP Architecture

The MCP implementation uses a dedicated background event loop (_mcp_loop) running in a daemon thread. Each server is represented by an MCPServerTask. tools/mcp_tool.py76-79 Stderr from MCP subprocesses is redirected to a shared log file ~/.hermes/logs/mcp-stderr.log to prevent TUI corruption. tools/mcp_tool.py135-140

MCP Client Integration System

Sources: tools/mcp_tool.py75-84 tools/mcp_tool.py135-156

2.2 Schema Mapping and Tool Registration

Tools discovered from MCP servers are converted into the agent's internal tool schema. tools/mcp_tool.py5-7

• Prefixing: Tool names are prefixed to avoid collisions with built-in tools. tests/tools/test_mcp_tool.py20-32
• Discovery: Servers are queried for tools, which are then registered in the global tool registry. tools/mcp_tool.py5-7
• Status Tracking: The system distinguishes between configured, connecting, failed, and disabled states. tests/tools/test_mcp_tool.py126-150

Sources: tools/mcp_tool.py5-7 tests/tools/test_mcp_tool.py126-173

2.3 OAuth 2.1 Support

For servers requiring browser-based authentication, mcp_oauth.py implements OAuth 2.1 with PKCE. tools/mcp_oauth.py3-7

• HermesTokenStorage: Persists tokens and client information to ~/.hermes/mcp-tokens/. tools/mcp_oauth.py134-145
• Secure Storage: Uses profile-specific directories to ensure tokens are isolated between agent profiles and stored with 0o600 permissions. tests/tools/test_mcp_oauth.py65-88
• Callback Server: Spawns an ephemeral HTTPServer on localhost to capture authorization codes. tools/mcp_oauth.py16-17 tools/mcp_oauth.py51
• Non-Interactive Environments: OAuthNonInteractiveError is raised if interaction is required but the environment is non-interactive. tools/mcp_oauth.py88-89

Sources: tools/mcp_oauth.py3-17 tools/mcp_oauth.py134-145 tests/tools/test_mcp_oauth.py65-88 tools/mcp_oauth.py88-89

2.4 Reliability and Security

• Credential Redaction: Error messages returned to the LLM are scrubbed of secrets. tools/mcp_tool.py67
• Auto-Reconnection: Implements automatic reconnection with exponential backoff. tools/mcp_tool.py65
• Parallelism: Supports a supports_parallel_tool_calls flag to allow concurrent execution of tools from the same server. tools/mcp_tool.py72-73
• Environment Filtering: Subprocesses are spawned with filtered environment variables to prevent leaking host secrets. tools/mcp_tool.py66

Sources: tools/mcp_tool.py62-74

---

3. Terminal and Process Management

The ProcessRegistry manages background processes spawned through terminal tools, providing buffering and lifecycle tracking. tools/process_registry.py2-10

3.1 Process Tracking

The ProcessRegistry singleton tracks ProcessSession objects, which contain metadata such as PID, command, and output buffers. tools/process_registry.py91-140

• Output Buffering: Maintains a rolling 200KB window (MAX_OUTPUT_CHARS) for process output. tools/process_registry.py58
• Crash Recovery: Persists process metadata to processes.json for recovery after gateway restarts. tools/process_registry.py55
• Rate Limiting: Implements WATCH_MIN_INTERVAL_SECONDS to prevent flooding the user with notifications from background tasks. tools/process_registry.py69

Sources: tools/process_registry.py2-10 tools/process_registry.py55-61 tools/process_registry.py91-140

3.2 Environment Sanitization

Local execution environments use a strict blocklist to prevent sensitive Hermes environment variables from leaking into spawned subprocesses. tools/environments/local.py139-151

• Provider Secrets: Variables matching _SECRET_SUBSTRINGS are explicitly blocked. tools/code_execution_tool.py148-158
• OS Essentials: On Windows, critical variables like SYSTEMROOT and COMSPEC are preserved in the sandbox to ensure basic system functionality. tools/code_execution_tool.py177-183
• CWD Recovery: The system can recover a usable cwd if the configured directory is deleted or inaccessible. tools/environments/local.py154-172

Sources: tools/environments/local.py139-172 tools/code_execution_tool.py145-183