MCP integration

Model Context Protocol (MCP) lets Hermes connect to external tool servers. Even in offline setups, MCP is useful for local services.

What MCP adds

• Connect to local databases, APIs, or custom scripts.
• Filter which tools from a server Hermes can use.
• Extend Hermes without modifying core code.

Offline MCP examples

MCP server	Use case
Local filesystem indexer	Search across large document archives
Git MCP	Rich git operations beyond shell
SQLite MCP	Query local databases
Custom script server	Your own automation endpoints

Configuring MCP

Add servers under mcp_servers in ~/.hermes/config.yaml. It's a map keyed by server name, not a list:

mcp_servers:
  local-git:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-git", "/path/to/repo"]

Hermes discovers available tools from each server and loads them on demand. After editing config, reload without restarting:

/reload-mcp

Safety

Review MCP servers before connecting

MCP servers can read and write to connected systems. Only add servers you trust, especially on your local machine with real data.

Filter tools per server to grant least privilege using tools.include (allowlist) or tools.exclude (blocklist):

mcp_servers:
  local-git:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-git", "/path/to/repo"]
    tools:
      include:
        - git_status
        - git_log
        - git_diff

When to use MCP vs. built-in tools

Use built-in	Use MCP
File read/write/edit	Custom domain logic
Shell commands	Structured API access
Code execution	Third-party integrations

For most offline workflows in this handbook, built-in filesystem and shell tools are enough. Add MCP when you need structured access to a specific local system.

Next: Scheduled tasks.