Interactive CLI Usage

Hermes MCP provides interactive command-line interfaces that allow you to directly interact with MCP servers. These CLI tools are useful for:

  • Testing and debugging MCP servers
  • Exploring available tools and resources
  • Rapid prototyping and development
  • Diagnostic purposes

Available CLI Tools

Hermes provides two built-in interactive CLIs:

  1. SSE Interactive: For connecting to HTTP/SSE MCP servers
  2. STDIO Interactive: For connecting to STDIO-based MCP servers

Starting the CLI

SSE Interactive

The SSE interactive CLI connects to HTTP-based MCP servers using Server-Sent Events (SSE).

mix hermes.sse.interactive --base-url=https://your-mcp-server.com

STDIO Interactive

The STDIO interactive CLI connects to subprocess-based MCP servers using standard input/output.

mix hermes.stdio.interactive --command=path/to/server --args=arg1,arg2

Command-Line Options

Both CLIs support the following common options:

OptionDescription
-h, --helpShow help message and exit
-vSet log level (accumulating flag)
No flag: :error level (default)
-v: :warning level
-vv: :info level
-vvv: :debug level

SSE Transport Options

OptionDescriptionDefault
--base-url URLBase URL for SSE serverhttp://localhost:8000
--base-path PATHBase path for the SSE server/
--sse-path PATHPath for SSE endpoint/sse

STDIO Transport Options

OptionDescriptionDefault
-c, --command CMDCommand to executemcp
--args ARGSComma-separated arguments for the commandrun,priv/dev/echo/index.py

Interactive Commands

Once connected, the CLI provides an interactive shell with several commands:

CommandDescription
helpShow list of available commands
pingSend a ping to the server to check connection health
list_toolsList available server tools
call_toolCall a server tool with arguments
list_promptsList available server prompts
get_promptGet a server prompt
list_resourcesList available server resources
read_resourceRead a server resource
show_stateShow internal state of client and transport
initializeRetry server connection initialization
clearClear the screen
exitExit the interactive session

Using the show_state Command

The show_state command provides detailed information about the internal state of both the client and transport processes. This is particularly useful for debugging connection issues.

mcp> show_state

This will display:

  • Client state information (protocol version, client info, server capabilities, etc.)
  • Transport state (connection details, status)
  • Pending requests (if any)

For more detailed error information, use the --verbose flag when starting the CLI or set the HERMES_VERBOSE=1 environment variable.

Examples

Connecting to a Local SSE Server

mix hermes.sse.interactive

Connecting to a Remote SSE Server

mix hermes.sse.interactive --base-url=https://remote-server.example.com --verbose

Running a Local MCP Server with STDIO

mix hermes.stdio.interactive --command=./my-mcp-server --args=arg1,arg2

Checking Server Connection

mcp> ping
# Shows if the server is responding with a pong

Calling a Tool

mcp> list_tools
# Lists available tools

mcp> call_tool
Tool name: calculator
Tool arguments (JSON): {"operation": "+", "a": 1, "b": 2}
# Returns: 3

Advanced Debugging

# Basic error-only logging (default)
mix hermes.sse.interactive

# Warning-level logging
mix hermes.sse.interactive -v

# Info-level logging
mix hermes.sse.interactive -vv

# Debug-level (most verbose) logging
mix hermes.sse.interactive -vvv

The verbosity level controls which log messages are displayed:

  • Default (no flags): Only errors are shown
  • -v: Errors and warnings are shown
  • -vv: Errors, warnings, and info messages are shown
  • -vvv: All messages including debug details are shown

Use the show_state command to see detailed internal state information, or examine extended error information when initialization fails.