/native-mcp

name: native-mcp
description: "MCP client: connect servers, register tools (stdio/HTTP)."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [MCP, Tools, Integrations]
    related_skills: [mcporter]

Native MCP Client

Hermes Agent has a built-in MCP client that connects to MCP servers at startup, discovers their tools, and makes them available as first-class tools the agent can call directly. No bridge CLI needed -- tools from MCP servers appear alongside built-in tools like `terminal`, `read_file`, etc.

When to Use

Use this whenever you want to:

• Connect to MCP servers and use their tools from within Hermes Agent
• Add external capabilities (filesystem access, GitHub, databases, APIs) via MCP
• Run local stdio-based MCP servers (npx, uvx, or any command)
• Connect to remote HTTP/StreamableHTTP MCP servers
• Have MCP tools auto-discovered and available in every conversation

For ad-hoc, one-off MCP tool calls from the terminal without configuring anything, see the `mcporter` skill instead.

Prerequisites

• **mcp Python package** -- optional dependency; install with `pip install mcp`. If not installed, MCP support is silently disabled.
• **Node.js** -- required for `npx`-based MCP servers (most community servers)
• **uv** -- required for `uvx`-based MCP servers (Python-based servers)

Install the MCP SDK:

pip install mcp
# or, if using uv:
uv pip install mcp

Quick Start

Add MCP servers to `~/.hermes/config.yaml` under the `mcp_servers` key:

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

Restart Hermes Agent. On startup it will: 1. Connect to the server 2. Discover available tools 3. Register them with the prefix `mcp_time_*` 4. Inject them into all platform toolsets

You can then use the tools naturally -- just ask the agent to get the current time.

Configuration Reference

Each entry under `mcp_servers` is a server name mapped to its config. There are two transport types: **stdio** (command-based) and **HTTP** (url-based).

Stdio Transport (command + args)

mcp_servers:
  server_name:
    command: "npx"             # (required) executable to run
    args: ["-y", "pkg-name"]   # (optional) command arguments, default: []
    env:                       # (optional) environment variables for the subprocess
      SOME_API_KEY: "value"
    timeout: 120               # (optional) per-tool-call timeout in seconds, default: 120
    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60

HTTP Transport (url)

mcp_servers:
  server_name:
    url: "https://my-server.example.com/mcp"   # (required) server URL
    headers:                                     # (optional) HTTP headers
      Authorization: "Bearer sk-..."
    timeout: 180               # (optional) per-tool-call timeout in seconds, default: 120
    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60

All Config Options

| Option | Type | Default | Description | |-------------------|--------|---------|---------------------------------------------------| | `command` | string | -- | Executable to run (stdio transport, required) | | `args` | list | `[]` | Arguments passed to the command | | `env` | dict | `{}` | Extra environment variables for the subprocess | | `url` | string | -- | Server URL (HTTP transport, required) | | `headers` | dict | `{}` | HTTP headers sent with every request | | `timeout` | int | `120` | Per-tool-call timeout in seconds | | `connect_timeout` | int | `60` | Timeout for initial connection and discovery |

Note: A server config must have either `command` (stdio) or `url` (HTTP), not both.

How It Works

Startup Discovery

When Hermes Agent starts, `discover_mcp_tools()` is called during tool initialization:

1. Reads `mcp_servers` from `~/.hermes/config.yaml` 2. For each server, spawns a connection in a dedicated background event loop 3. Initializes the MCP session and calls `list_tools()` to discover available tools 4. Registers each tool in the Hermes tool registry

Tool Naming Convention

MCP tools are registered with the naming pattern:

mcp_{server_name}_{tool_name}

Hyphens and dots in names are replaced with underscores for LLM API compatibility.

Examples:

• Server `filesystem`, tool `read_file` → `mcp_filesystem_read_file`
• Server `github`, tool `list-issues` → `mcp_github_list_issues`
• Server `my-api`, tool `fetch.data` → `mcp_my_api_fetch_data`

Auto-Injection

After discovery, MCP tools are automatically injected into all `hermes-*` platform toolsets (CLI, Discord, Telegram, etc.). This means MCP tools are available in every conversation without any additional configuration.

Connection Lifecycle

• Each server runs as a long-lived asyncio Task in a background daemon thread
• Connections persist for the lifetime of the agent process
• If a connection drops, automatic reconnection with exponential backoff kicks in (up to 5 retries, max 60s backoff)
• On agent shutdown, all connections are gracefully closed

Idempotency

`discover_mcp_tools()` is idempotent -- calling it multiple times only connects to servers that aren't already connected. Failed servers are retried on subsequent calls.

Transport Types

Stdio Transport

The most common transport. Hermes launches the MCP server as a subprocess and communicates over stdin/stdout.

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

The subprocess inherits a **filtered** environment (see Security section below) plus any variables you specify in `env`.

HTTP / St