Merge pull request #301 from NousResearch/feat/mcp-support

feat(mcp): Native MCP client with HTTP transport, reconnection, and security
2026-04-25 00:51:20 +00:00 · 2026-03-02 21:32:43 -08:00 · 2026-03-02 21:32:43 -08:00 · 68cc81a74d
commit 68cc81a74d
parent 14b0ad95c6 3ead3401e0
15 changed files with 3776 additions and 27 deletions
--- a/README.md
+++ b/README.md
@ -496,6 +496,23 @@ hermes tools

 **Available toolsets:** `web`, `terminal`, `file`, `browser`, `vision`, `image_gen`, `moa`, `skills`, `tts`, `todo`, `memory`, `session_search`, `cronjob`, `code_execution`, `delegation`, `clarify`, and more.

+### 🔌 MCP (Model Context Protocol)
+
+Connect to any MCP-compatible server to extend Hermes with external tools. Just add servers to your config:
+
+```yaml
+mcp_servers:
+  time:
+    command: uvx
+    args: ["mcp-server-time"]
+  notion:
+    url: https://mcp.notion.com/mcp
+```
+
+Supports stdio and HTTP transports, auto-reconnection, and env var filtering. See [docs/mcp.md](docs/mcp.md) for details.
+
+Install MCP support: `pip install hermes-agent[mcp]`
+
 ### 🖥️ Terminal & Process Management

 The terminal tool can execute commands in different environments, with full background process management via the `process` tool:
--- a/TODO.md
+++ b/TODO.md
@ -63,33 +63,27 @@ Full Python plugin interface that goes beyond the current hook system.
 - `hermes plugin list|install|uninstall|create` CLI commands
 - Plugin discovery and validation on startup

-### Phase 3: MCP support (industry standard)
- MCP client that can connect to external MCP servers (stdio, SSE, HTTP)
- This is the big one -- Codex, Cline, and OpenCode all support MCP
- Allows Hermes to use any MCP-compatible tool server (hundreds exist)
- Config: `mcp_servers` list in config.yaml with connection details
- Each MCP server's tools get registered as a new toolset
+### Phase 3: MCP support (industry standard) ✅ DONE
+- ✅ MCP client that connects to external MCP servers (stdio + HTTP/StreamableHTTP)
+- ✅ Config: `mcp_servers` in config.yaml with connection details
+- ✅ Each MCP server's tools auto-registered as a dynamic toolset
+- Future: Resources, Prompts, Progress notifications, `hermes mcp` CLI command

 ---

-## 6. MCP (Model Context Protocol) Support 🔗
+## 6. MCP (Model Context Protocol) Support 🔗 ✅ DONE

-**Status:** Not started
-**Priority:** High -- this is becoming an industry standard
+**Status:** Implemented (PR #301)
+**Priority:** Complete

-MCP is the protocol that Codex, Cline, and OpenCode all support for connecting to external tool servers. Supporting MCP would instantly give Hermes access to hundreds of community tool servers.
+Native MCP client support with stdio and HTTP/StreamableHTTP transports, auto-discovery, reconnection with exponential backoff, env var filtering, and credential stripping. See `docs/mcp.md` for full documentation.

-**What other agents do:**
- **Codex**: Full MCP integration with skill dependencies
- **Cline**: `use_mcp_tool` / `access_mcp_resource` / `load_mcp_documentation` tools
- **OpenCode**: MCP client support (stdio, SSE, StreamableHTTP transports), OAuth auth
-
-**Our approach:**
- Implement an MCP client that can connect to external MCP servers
- Config: list of MCP servers in `~/.hermes/config.yaml` with transport type and connection details
- Each MCP server's tools auto-registered as a dynamic toolset
- Start with stdio transport (most common), then add SSE and HTTP
- Could also be part of the Plugin system (#5, Phase 3) since MCP is essentially a plugin protocol
+**Still TODO:**
+- `hermes mcp` CLI subcommand (list/test/status)
+- `hermes tools` UI integration for MCP toolsets
+- MCP Resources and Prompts support
+- OAuth authentication for remote servers
+- Progress notifications for long-running tools

 ---

@ -121,7 +115,7 @@ Automatic filesystem snapshots after each agent loop iteration so the user can r

 ### Tier 1: Next Up

-1. MCP Support -- #6
+1. ~~MCP Support -- #6~~ ✅ Done (PR #301)

 ### Tier 2: Quality of Life

--- a/cli-config.yaml.example
+++ b/cli-config.yaml.example
@ -442,6 +442,41 @@ toolsets:
 # toolsets:
 #   - safe

+# =============================================================================
+# MCP (Model Context Protocol) Servers
+# =============================================================================
+# Connect to external MCP servers to add tools from the MCP ecosystem.
+# Each server's tools are automatically discovered and registered.
+# See docs/mcp.md for full documentation.
+#
+# Stdio servers (spawn a subprocess):
+#   command: the executable to run
+#   args: command-line arguments
+#   env: environment variables (only these + safe defaults passed to subprocess)
+#
+# HTTP servers (connect to a URL):
+#   url: the MCP server endpoint
+#   headers: HTTP headers (e.g., for authentication)
+#
+# Optional per-server settings:
+#   timeout: tool call timeout in seconds (default: 120)
+#   connect_timeout: initial connection timeout (default: 60)
+#
+# mcp_servers:
+#   time:
+#     command: uvx
+#     args: ["mcp-server-time"]
+#   filesystem:
+#     command: npx
+#     args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
+#   notion:
+#     url: https://mcp.notion.com/mcp
+#   github:
+#     command: npx
+#     args: ["-y", "@modelcontextprotocol/server-github"]
+#     env:
+#       GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
+
 # =============================================================================
 # Voice Transcription (Speech-to-Text)
 # =============================================================================
--- a/cli.py
+++ b/cli.py
@ -386,6 +386,11 @@ def _run_cleanup():
        _cleanup_all_browsers()
    except Exception:
        pass
+    try:
+        from tools.mcp_tool import shutdown_mcp_servers
+        shutdown_mcp_servers()
+    except Exception:
+        pass

 # ============================================================================
 # ASCII Art & Branding
@ -685,6 +690,7 @@ COMMANDS = {
    "/cron": "Manage scheduled tasks (list, add, remove)",
    "/skills": "Search, install, inspect, or manage skills from online registries",
    "/platforms": "Show gateway/messaging platform status",
+    "/reload-mcp": "Reload MCP servers from config.yaml",
    "/quit": "Exit the CLI (also: /exit, /q)",
 }

@ -1765,6 +1771,8 @@ class HermesCLI:
            self._manual_compress()
        elif cmd_lower == "/usage":
            self._show_usage()
+        elif cmd_lower == "/reload-mcp":
+            self._reload_mcp()
        else:
            # Check for skill slash commands (/gif-search, /axolotl, etc.)
            base_cmd = cmd_lower.split()[0]
@ -1886,6 +1894,91 @@ class HermesCLI:
            for quiet_logger in ('tools', 'minisweagent', 'run_agent', 'trajectory_compressor', 'cron', 'hermes_cli'):
                logging.getLogger(quiet_logger).setLevel(logging.ERROR)

+    def _reload_mcp(self):
+        """Reload MCP servers: disconnect all, re-read config.yaml, reconnect.
+
+        After reconnecting, refreshes the agent's tool list so the model
+        sees the updated tools on the next turn.
+        """
+        try:
+            from tools.mcp_tool import shutdown_mcp_servers, discover_mcp_tools, _load_mcp_config, _servers, _lock
+
+            # Capture old server names
+            with _lock:
+                old_servers = set(_servers.keys())
+
+            print("🔄 Reloading MCP servers...")
+
+            # Shutdown existing connections
+            shutdown_mcp_servers()
+
+            # Reconnect (reads config.yaml fresh)
+            new_tools = discover_mcp_tools()
+
+            # Compute what changed
+            with _lock:
+                connected_servers = set(_servers.keys())
+
+            added = connected_servers - old_servers
+            removed = old_servers - connected_servers
+            reconnected = connected_servers & old_servers
+
+            if reconnected:
+                print(f"  ♻️  Reconnected: {', '.join(sorted(reconnected))}")
+            if added:
+                print(f"  ➕ Added: {', '.join(sorted(added))}")
+            if removed:
+                print(f"  ➖ Removed: {', '.join(sorted(removed))}")
+            if not connected_servers:
+                print("  No MCP servers connected.")
+            else:
+                print(f"  🔧 {len(new_tools)} tool(s) available from {len(connected_servers)} server(s)")
+
+            # Refresh the agent's tool list so the model can call new tools
+            if self.agent is not None:
+                from model_tools import get_tool_definitions
+                self.agent.tools = get_tool_definitions(
+                    enabled_toolsets=self.agent.enabled_toolsets
+                    if hasattr(self.agent, "enabled_toolsets") else None,
+                    quiet_mode=True,
+                )
+                self.agent.valid_tool_names = {
+                    tool["function"]["name"] for tool in self.agent.tools
+                } if self.agent.tools else set()
+
+            # Inject a message at the END of conversation history so the
+            # model knows tools changed.  Appended after all existing
+            # messages to preserve prompt-cache for the prefix.
+            change_parts = []
+            if added:
+                change_parts.append(f"Added servers: {', '.join(sorted(added))}")
+            if removed:
+                change_parts.append(f"Removed servers: {', '.join(sorted(removed))}")
+            if reconnected:
+                change_parts.append(f"Reconnected servers: {', '.join(sorted(reconnected))}")
+            tool_summary = f"{len(new_tools)} MCP tool(s) now available" if new_tools else "No MCP tools available"
+            change_detail = ". ".join(change_parts) + ". " if change_parts else ""
+            self.conversation_history.append({
+                "role": "user",
+                "content": f"[SYSTEM: MCP servers have been reloaded. {change_detail}{tool_summary}. The tool list for this conversation has been updated accordingly.]",
+            })
+
+            # Persist session immediately so the session log reflects the
+            # updated tools list (self.agent.tools was refreshed above).
+            if self.agent is not None:
+                try:
+                    self.agent._persist_session(
+                        self.conversation_history,
+                        self.conversation_history,
+                    )
+                except Exception:
+                    pass  # Best-effort
+
+            print(f"  ✅ Agent updated — {len(self.agent.tools if self.agent else [])} tool(s) available")
+
+        except Exception as e:
+            print(f"  ❌ MCP reload failed: {e}")
+
    def _clarify_callback(self, question, choices):
        """
        Platform callback for the clarify tool. Called from the agent thread.
--- a/docs/mcp.md
+++ b/docs/mcp.md
@ -0,0 +1,527 @@
+# MCP (Model Context Protocol) Support
+
+MCP lets Hermes Agent connect to external tool servers — giving the agent access to databases, APIs, filesystems, and more without any code changes.
+
+## Overview
+
+The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open standard for connecting AI agents to external tools and data sources. MCP servers expose tools over a lightweight RPC protocol, and Hermes Agent can connect to any compliant server automatically.
+
+What this means for you:
+
+- **Thousands of ready-made tools** — browse the [MCP server directory](https://github.com/modelcontextprotocol/servers) for servers covering GitHub, Slack, databases, file systems, web scraping, and more.
+- **No code changes needed** — add a few lines to `~/.hermes/config.yaml` and the tools appear alongside built-in ones.
+- **Mix and match** — run multiple MCP servers simultaneously, combining stdio-based and HTTP-based servers.
+- **Secure by default** — environment variables are filtered and credentials are stripped from error messages returned to the LLM.
+
+## Prerequisites
+
+Install MCP support as an optional dependency:
+
+```bash
+pip install hermes-agent[mcp]
+```
+
+Depending on which MCP servers you want to use, you may need additional runtimes:
+
+| Server Type | Runtime Needed | Example |
+|-------------|---------------|---------|
+| HTTP/remote | Nothing extra | `url: "https://mcp.example.com"` |
+| npm-based (npx) | Node.js 18+ | `command: "npx"` |
+| Python-based | uv (recommended) | `command: "uvx"` |
+
+Most popular MCP servers are distributed as npm packages and launched via `npx`. Python-based servers typically use `uvx` (from the [uv](https://docs.astral.sh/uv/) package manager).
+
+## Configuration
+
+MCP servers are configured in `~/.hermes/config.yaml` under the `mcp_servers` key. Each entry is a named server with its connection details.
+
+### Stdio Servers (command + args + env)
+
+Stdio servers run as local subprocesses. Communication happens over stdin/stdout.
+
+```yaml
+mcp_servers:
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
+    env: {}
+
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxx"
+```
+
+| Key | Required | Description |
+|-----|----------|-------------|
+| `command` | Yes | Executable to run (e.g., `npx`, `uvx`, `python`) |
+| `args` | No | List of command-line arguments |
+| `env` | No | Environment variables to pass to the subprocess |
+
+**Note:** Only explicitly listed `env` variables plus a safe baseline (PATH, HOME, USER, LANG, SHELL, TMPDIR, XDG_*) are passed to the subprocess. Your shell's API keys, tokens, and secrets are **not** leaked. See [Security](#security) for details.
+
+### HTTP Servers (url + headers)
+
+HTTP servers run remotely and are accessed over HTTP/StreamableHTTP.
+
+```yaml
+mcp_servers:
+  remote_api:
+    url: "https://my-mcp-server.example.com/mcp"
+    headers:
+      Authorization: "Bearer sk-xxxxxxxxxxxx"
+```
+
+| Key | Required | Description |
+|-----|----------|-------------|
+| `url` | Yes | Full URL of the MCP HTTP endpoint |
+| `headers` | No | HTTP headers to include (e.g., auth tokens) |
+
+### Per-Server Timeouts
+
+Each server can have custom timeouts:
+
+```yaml
+mcp_servers:
+  slow_database:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-postgres"]
+    env:
+      DATABASE_URL: "postgres://user:pass@localhost/mydb"
+    timeout: 300          # Tool call timeout in seconds (default: 120)
+    connect_timeout: 90   # Initial connection timeout in seconds (default: 60)
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `timeout` | 120 | Maximum seconds to wait for a single tool call to complete |
+| `connect_timeout` | 60 | Maximum seconds to wait for the initial connection and tool discovery |
+
+### Mixed Configuration Example
+
+You can combine stdio and HTTP servers freely:
+
+```yaml
+mcp_servers:
+  # Local filesystem access via stdio
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+
+  # GitHub API via stdio with auth
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxx"
+
+  # Remote database via HTTP
+  company_db:
+    url: "https://mcp.internal.company.com/db"
+    headers:
+      Authorization: "Bearer sk-xxxxxxxxxxxx"
+    timeout: 180
+
+  # Python-based server via uvx
+  memory:
+    command: "uvx"
+    args: ["mcp-server-memory"]
+```
+
+## Config Translation (Claude/Cursor JSON → Hermes YAML)
+
+Many MCP server docs show configuration in Claude Desktop JSON format. Here's how to translate:
+
+**Claude Desktop JSON** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+      "env": {}
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+**Hermes Agent YAML** (`~/.hermes/config.yaml`):
+
+```yaml
+mcp_servers:                          # mcpServers → mcp_servers (snake_case)
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    env: {}
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxx"
+```
+
+Translation rules:
+
+1. **Key name**: `mcpServers` → `mcp_servers` (snake_case)
+2. **Format**: JSON → YAML (remove braces/brackets, use indentation)
+3. **Arrays**: `["a", "b"]` stays the same in YAML flow style, or use block style with `- a`
+4. **Everything else**: Keys (`command`, `args`, `env`) are identical
+
+## How It Works
+
+### Startup & Discovery
+
+When Hermes Agent starts, the tool discovery system calls `discover_mcp_tools()`:
+
+1. **Config loading** — Reads `mcp_servers` from `~/.hermes/config.yaml`
+2. **Background loop** — Spins up a dedicated asyncio event loop in a daemon thread for MCP connections
+3. **Connection** — Connects to each configured server (stdio subprocess or HTTP)
+4. **Session init** — Initializes the MCP client session (protocol handshake)
+5. **Tool discovery** — Calls `list_tools()` on each server to get available tools
+6. **Registration** — Registers each MCP tool into the Hermes tool registry with a prefixed name
+
+### Tool Registration
+
+Each discovered MCP tool is registered with a prefixed name following this pattern:
+
+```
+mcp_{server_name}_{tool_name}
+```
+
+Hyphens and dots in both server and tool names are replaced with underscores for API compatibility. For example:
+
+| Server Name | MCP Tool Name | Registered As |
+|-------------|--------------|---------------|
+| `filesystem` | `read_file` | `mcp_filesystem_read_file` |
+| `github` | `create-issue` | `mcp_github_create_issue` |
+| `my-api` | `query.data` | `mcp_my_api_query_data` |
+
+Tools appear alongside built-in tools — the agent sees them in its tool list and can call them like any other tool.
+
+### Tool Calling
+
+When the agent calls an MCP tool:
+
+1. The handler is invoked by the tool registry (sync interface)
+2. The handler schedules the actual MCP `call_tool()` RPC on the background event loop
+3. The call blocks (with timeout) until the MCP server responds
+4. Response content blocks are collected and returned as JSON
+5. Errors are sanitized to strip credentials before returning to the LLM
+
+### Shutdown
+
+On agent exit, `shutdown_mcp_servers()` is called:
+
+1. All server tasks are signalled to exit via their shutdown events
+2. Each server's `async with` context manager exits, cleaning up transports
+3. The background event loop is stopped and its thread is joined
+4. All server state is cleared
+
+## Security
+
+### Environment Variable Filtering
+
+When launching stdio MCP servers, Hermes does **not** pass your full shell environment to the subprocess. The `_build_safe_env()` function constructs a minimal environment:
+
+**Always passed through** (from your current environment):
+- `PATH`, `HOME`, `USER`, `LANG`, `LC_ALL`, `TERM`, `SHELL`, `TMPDIR`
+- Any variable starting with `XDG_`
+
+**Explicitly added**: Any variables you list in the server's `env` config.
+
+**Everything else is excluded** — your `OPENAI_API_KEY`, `AWS_SECRET_ACCESS_KEY`, database passwords, and other secrets are never leaked to MCP server subprocesses unless you explicitly add them.
+
+```yaml
+mcp_servers:
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      # Only this token is passed — nothing else from your shell
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxx"
+```
+
+### Credential Stripping in Errors
+
+If an MCP tool call fails, the error message is sanitized by `_sanitize_error()` before being returned to the LLM. The following patterns are replaced with `[REDACTED]`:
+
+- GitHub PATs (`ghp_...`)
+- OpenAI-style keys (`sk-...`)
+- Bearer tokens (`Bearer ...`)
+- Query parameters (`token=...`, `key=...`, `API_KEY=...`, `password=...`, `secret=...`)
+
+This prevents accidental credential exposure through error messages in the conversation.
+
+## Transport Types
+
+### Stdio Transport
+
+The default transport for locally-installed MCP servers. The server runs as a subprocess and communicates over stdin/stdout.
+
+```yaml
+mcp_servers:
+  my_server:
+    command: "npx"           # or "uvx", "python", any executable
+    args: ["-y", "package"]
+    env:
+      MY_VAR: "value"
+```
+
+**Pros:** Simple setup, no network needed, works offline.
+**Cons:** Server must be installed locally, one process per server.
+
+### HTTP / StreamableHTTP Transport
+
+For remote MCP servers accessible over HTTP. Uses the StreamableHTTP protocol from the MCP SDK.
+
+```yaml
+mcp_servers:
+  my_remote:
+    url: "https://mcp.example.com/endpoint"
+    headers:
+      Authorization: "Bearer token"
+```
+
+**Pros:** No local installation needed, shared servers, cloud-hosted.
+**Cons:** Requires network, slightly higher latency, needs `mcp` package with HTTP support.
+
+**Note:** If HTTP transport is not available in your installed `mcp` package version, Hermes will log a clear error and skip that server.
+
+## Reconnection
+
+If an MCP server connection drops after initial setup (e.g., process crash, network hiccup), Hermes automatically attempts to reconnect with exponential backoff:
+
+| Attempt | Delay Before Retry |
+|---------|--------------------|
+| 1 | 1 second |
+| 2 | 2 seconds |
+| 3 | 4 seconds |
+| 4 | 8 seconds |
+| 5 | 16 seconds |
+
+- Maximum of **5 retry attempts** before giving up
+- Backoff is capped at **60 seconds** (relevant if the formula exceeds this)
+- Reconnection only triggers for **established connections** that drop — initial connection failures are reported immediately without retries
+- If shutdown is requested during reconnection, the retry loop exits cleanly
+
+## Troubleshooting
+
+### Common Errors
+
+**"mcp package not installed"**
+
+```
+MCP SDK not available -- skipping MCP tool discovery
+```
+
+Solution: Install the MCP optional dependency:
+
+```bash
+pip install hermes-agent[mcp]
+```
+
+---
+
+**"command not found" or server fails to start**
+
+The MCP server command (`npx`, `uvx`, etc.) is not on PATH.
+
+Solution: Install the required runtime:
+
+```bash
+# For npm-based servers
+npm install -g npx    # or ensure Node.js 18+ is installed
+
+# For Python-based servers
+pip install uv        # then use "uvx" as the command
+```
+
+---
+
+**"MCP server 'X' has no 'command' in config"**
+
+Your stdio server config is missing the `command` key.
+
+Solution: Check your `~/.hermes/config.yaml` indentation and ensure `command` is present:
+
+```yaml
+mcp_servers:
+  my_server:
+    command: "npx"        # <-- required for stdio servers
+    args: ["-y", "package-name"]
+```
+
+---
+
+**Server connects but tools fail with authentication errors**
+
+Your API key or token is missing or invalid.
+
+Solution: Ensure the key is in the server's `env` block (not your shell env):
+
+```yaml
+mcp_servers:
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_your_actual_token"  # <-- check this
+```
+
+---
+
+**"MCP server 'X' is not connected"**
+
+The server disconnected and reconnection failed (or was never established).
+
+Solution:
+1. Check the Hermes logs for connection errors (`hermes --verbose`)
+2. Verify the server works standalone (e.g., run the `npx` command manually)
+3. Increase `connect_timeout` if the server is slow to start
+
+---
+
+**Connection timeout during discovery**
+
+```
+Failed to connect to MCP server 'X': TimeoutError
+```
+
+Solution: Increase the `connect_timeout` for slow-starting servers:
+
+```yaml
+mcp_servers:
+  slow_server:
+    command: "npx"
+    args: ["-y", "heavy-server-package"]
+    connect_timeout: 120   # default is 60
+```
+
+---
+
+**HTTP transport not available**
+
+```
+mcp.client.streamable_http is not available
+```
+
+Solution: Upgrade the `mcp` package to a version that includes HTTP support:
+
+```bash
+pip install --upgrade mcp
+```
+
+## Popular MCP Servers
+
+Here are some popular free MCP servers you can use immediately:
+
+| Server | Package | Description |
+|--------|---------|-------------|
+| Filesystem | `@modelcontextprotocol/server-filesystem` | Read/write/search local files |
+| GitHub | `@modelcontextprotocol/server-github` | Issues, PRs, repos, code search |
+| Git | `@modelcontextprotocol/server-git` | Git operations on local repos |
+| Fetch | `@modelcontextprotocol/server-fetch` | HTTP fetching and web content extraction |
+| Memory | `@modelcontextprotocol/server-memory` | Persistent key-value memory |
+| SQLite | `@modelcontextprotocol/server-sqlite` | Query SQLite databases |
+| PostgreSQL | `@modelcontextprotocol/server-postgres` | Query PostgreSQL databases |
+| Brave Search | `@modelcontextprotocol/server-brave-search` | Web search via Brave API |
+| Puppeteer | `@modelcontextprotocol/server-puppeteer` | Browser automation |
+| Sequential Thinking | `@modelcontextprotocol/server-sequential-thinking` | Step-by-step reasoning |
+
+### Example Configs for Popular Servers
+
+```yaml
+mcp_servers:
+  # Filesystem — no API key needed
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
+
+  # Git — no API key needed
+  git:
+    command: "uvx"
+    args: ["mcp-server-git", "--repository", "/home/user/my-repo"]
+
+  # GitHub — requires a personal access token
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxx"
+
+  # Fetch — no API key needed
+  fetch:
+    command: "uvx"
+    args: ["mcp-server-fetch"]
+
+  # SQLite — no API key needed
+  sqlite:
+    command: "uvx"
+    args: ["mcp-server-sqlite", "--db-path", "/home/user/data.db"]
+
+  # Brave Search — requires API key (free tier available)
+  brave_search:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-brave-search"]
+    env:
+      BRAVE_API_KEY: "BSA_xxxxxxxxxxxx"
+```
+
+## Advanced
+
+### Multiple Servers
+
+You can run as many MCP servers as you want simultaneously. Each server gets its own subprocess (stdio) or HTTP connection, and all tools are registered into a single unified namespace.
+
+Servers are connected sequentially during startup. If one server fails to connect, the others still work — failed servers are logged as warnings and skipped.
+
+### Tool Naming Convention
+
+All MCP tools follow the naming pattern:
+
+```
+mcp_{server_name}_{tool_name}
+```
+
+Both the server name and tool name are sanitized: hyphens (`-`) and dots (`.`) are replaced with underscores (`_`). This ensures compatibility with LLM function-calling APIs that restrict tool name characters.
+
+If you configure a server named `my-api` that exposes a tool called `query.users`, the agent will see it as `mcp_my_api_query_users`.
+
+### Configurable Timeouts
+
+Fine-tune timeouts per server based on expected response times:
+
+```yaml
+mcp_servers:
+  fast_cache:
+    command: "npx"
+    args: ["-y", "mcp-server-redis"]
+    timeout: 30            # Fast lookups — short timeout
+    connect_timeout: 15
+
+  slow_analysis:
+    url: "https://analysis.example.com/mcp"
+    timeout: 600           # Long-running analysis — generous timeout
+    connect_timeout: 120
+```
+
+### Idempotent Discovery
+
+`discover_mcp_tools()` is idempotent — calling it multiple times only connects to servers that aren't already running. Already-connected servers keep their existing connections and tool registrations.
+
+### Custom Toolsets
+
+Each MCP server's tools are automatically grouped into a toolset named `mcp-{server_name}`. These toolsets are also injected into all `hermes-*` platform toolsets, so MCP tools are available in CLI, Telegram, Discord, and other platforms.
+
+### Thread Safety
+
+The MCP subsystem is fully thread-safe. A dedicated background event loop runs in a daemon thread, and all server state is protected by a lock. This works correctly even with Python 3.13+ free-threading builds.
--- a/docs/tools.md
+++ b/docs/tools.md
@ -55,6 +55,7 @@ async def web_search(query: str) -> dict:
 | **Clarify** | `clarify_tool.py` | `clarify` (interactive multiple-choice / open-ended questions, CLI-only) |
 | **Code Execution** | `code_execution_tool.py` | `execute_code` (run Python scripts that call tools via RPC sandbox) |
 | **Delegation** | `delegate_tool.py` | `delegate_task` (spawn subagents with isolated context, single + parallel batch) |
+| **MCP (External)** | `tools/mcp_tool.py` | Auto-discovered from configured MCP servers |

 ## Tool Registration

@ -414,3 +415,20 @@ The Skills Hub enables searching, installing, and managing skills from online re

 **CLI:** `hermes skills search|install|inspect|list|audit|uninstall|publish|snapshot|tap`
 **Slash:** `/skills search|install|inspect|list|audit|uninstall|publish|snapshot|tap`
+
+## MCP Tools
+
+MCP (Model Context Protocol) tools are **dynamically registered** from external MCP servers configured in `cli-config.yaml`. Unlike built-in tools which are defined in Python source files, MCP tools are discovered at startup by connecting to each configured server and querying its available tools.
+
+Each MCP tool is automatically wrapped with an OpenAI-compatible schema and registered in the tool registry under the `mcp` toolset. Tool names are prefixed with the server name (e.g., `time__get_current_time`) to avoid collisions.
+
+**Key characteristics:**
+- Tools are discovered and registered at agent startup — no code changes needed
+- Supports both stdio (subprocess) and HTTP (streamable HTTP) transports
+- Auto-reconnects on connection failures with exponential backoff
+- Environment variables passed to stdio servers are filtered for security
+- Each server can have independent timeout settings
+
+**Configuration:** Add servers to `mcp_servers` in `cli-config.yaml`. See [docs/mcp.md](mcp.md) for full documentation.
+
+**Installation:** MCP support requires the optional `mcp` extra: `pip install hermes-agent[mcp]`
--- a/gateway/run.py
+++ b/gateway/run.py
@ -645,7 +645,7 @@ class GatewayRunner:
        # Emit command:* hook for any recognized slash command
        _known_commands = {"new", "reset", "help", "status", "stop", "model",
                          "personality", "retry", "undo", "sethome", "set-home",
-                          "compress", "usage"}
+                          "compress", "usage", "reload-mcp"}
        if command and command in _known_commands:
            await self.hooks.emit(f"command:{command}", {
                "platform": source.platform.value if source.platform else "",
@ -686,6 +686,9 @@ class GatewayRunner:

        if command == "usage":
            return await self._handle_usage_command(event)
+
+        if command == "reload-mcp":
+            return await self._handle_reload_mcp_command(event)
        
        # Skill slash commands: /skill-name loads the skill and sends to agent
        if command:
@ -1086,6 +1089,7 @@ class GatewayRunner:
            "`/sethome` — Set this chat as the home channel",
            "`/compress` — Compress conversation context",
            "`/usage` — Show token usage for this session",
+            "`/reload-mcp` — Reload MCP servers from config",
            "`/help` — Show this message",
        ]
        try:
@ -1379,6 +1383,76 @@ class GatewayRunner:
            )
        return "No usage data available for this session."

+    async def _handle_reload_mcp_command(self, event: MessageEvent) -> str:
+        """Handle /reload-mcp command -- disconnect and reconnect all MCP servers."""
+        loop = asyncio.get_event_loop()
+        try:
+            from tools.mcp_tool import shutdown_mcp_servers, discover_mcp_tools, _load_mcp_config, _servers, _lock
+
+            # Capture old server names before shutdown
+            with _lock:
+                old_servers = set(_servers.keys())
+
+            # Read new config before shutting down, so we know what will be added/removed
+            new_config = _load_mcp_config()
+            new_server_names = set(new_config.keys())
+
+            # Shutdown existing connections
+            await loop.run_in_executor(None, shutdown_mcp_servers)
+
+            # Reconnect by discovering tools (reads config.yaml fresh)
+            new_tools = await loop.run_in_executor(None, discover_mcp_tools)
+
+            # Compute what changed
+            with _lock:
+                connected_servers = set(_servers.keys())
+
+            added = connected_servers - old_servers
+            removed = old_servers - connected_servers
+            reconnected = connected_servers & old_servers
+
+            lines = ["🔄 **MCP Servers Reloaded**\n"]
+            if reconnected:
+                lines.append(f"♻️ Reconnected: {', '.join(sorted(reconnected))}")
+            if added:
+                lines.append(f"➕ Added: {', '.join(sorted(added))}")
+            if removed:
+                lines.append(f"➖ Removed: {', '.join(sorted(removed))}")
+            if not connected_servers:
+                lines.append("No MCP servers connected.")
+            else:
+                lines.append(f"\n🔧 {len(new_tools)} tool(s) available from {len(connected_servers)} server(s)")
+
+            # Inject a message at the END of the session history so the
+            # model knows tools changed on its next turn.  Appended after
+            # all existing messages to preserve prompt-cache for the prefix.
+            change_parts = []
+            if added:
+                change_parts.append(f"Added servers: {', '.join(sorted(added))}")
+            if removed:
+                change_parts.append(f"Removed servers: {', '.join(sorted(removed))}")
+            if reconnected:
+                change_parts.append(f"Reconnected servers: {', '.join(sorted(reconnected))}")
+            tool_summary = f"{len(new_tools)} MCP tool(s) now available" if new_tools else "No MCP tools available"
+            change_detail = ". ".join(change_parts) + ". " if change_parts else ""
+            reload_msg = {
+                "role": "user",
+                "content": f"[SYSTEM: MCP servers have been reloaded. {change_detail}{tool_summary}. The tool list for this conversation has been updated accordingly.]",
+            }
+            try:
+                session_entry = self.session_store.get_or_create_session(event.source)
+                self.session_store.append_to_transcript(
+                    session_entry.session_id, reload_msg
+                )
+            except Exception:
+                pass  # Best-effort; don't fail the reload over a transcript write
+
+            return "\n".join(lines)
+
+        except Exception as e:
+            logger.warning("MCP reload failed: %s", e)
+            return f"❌ MCP reload failed: {e}"
+
    def _set_session_env(self, context: SessionContext) -> None:
        """Set environment variables for the current session."""
        os.environ["HERMES_SESSION_PLATFORM"] = context.source.platform.value
@ -2217,7 +2291,14 @@ async def start_gateway(config: Optional[GatewayConfig] = None) -> bool:
    # Stop cron ticker cleanly
    cron_stop.set()
    cron_thread.join(timeout=5)
-    
+
+    # Close MCP server connections
+    try:
+        from tools.mcp_tool import shutdown_mcp_servers
+        shutdown_mcp_servers()
+    except Exception:
+        pass
+
    return True


--- a/hermes_cli/banner.py
+++ b/hermes_cli/banner.py
@ -196,6 +196,28 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
    if remaining_toolsets > 0:
        right_lines.append(f"[dim #B8860B](and {remaining_toolsets} more toolsets...)[/]")

+    # MCP Servers section (only if configured)
+    try:
+        from tools.mcp_tool import get_mcp_status
+        mcp_status = get_mcp_status()
+    except Exception:
+        mcp_status = []
+
+    if mcp_status:
+        right_lines.append("")
+        right_lines.append("[bold #FFBF00]MCP Servers[/]")
+        for srv in mcp_status:
+            if srv["connected"]:
+                right_lines.append(
+                    f"[dim #B8860B]{srv['name']}[/] [#FFF8DC]({srv['transport']})[/] "
+                    f"[dim #B8860B]—[/] [#FFF8DC]{srv['tools']} tool(s)[/]"
+                )
+            else:
+                right_lines.append(
+                    f"[red]{srv['name']}[/] [dim]({srv['transport']})[/] "
+                    f"[red]— failed[/]"
+                )
+
    right_lines.append("")
    right_lines.append("[bold #FFBF00]Available Skills[/]")
    skills_by_category = get_available_skills()
@ -216,7 +238,12 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
        right_lines.append("[dim #B8860B]No skills installed[/]")

    right_lines.append("")
-    right_lines.append(f"[dim #B8860B]{len(tools)} tools · {total_skills} skills · /help for commands[/]")
+    mcp_connected = sum(1 for s in mcp_status if s["connected"]) if mcp_status else 0
+    summary_parts = [f"{len(tools)} tools", f"{total_skills} skills"]
+    if mcp_connected:
+        summary_parts.append(f"{mcp_connected} MCP servers")
+    summary_parts.append("/help for commands")
+    right_lines.append(f"[dim #B8860B]{' · '.join(summary_parts)}[/]")

    right_content = "\n".join(right_lines)
    layout_table.add_row(left_content, right_content)
--- a/model_tools.py
+++ b/model_tools.py
@ -105,6 +105,13 @@ def _discover_tools():

 _discover_tools()

+# MCP tool discovery (external MCP servers from config)
+try:
+    from tools.mcp_tool import discover_mcp_tools
+    discover_mcp_tools()
+except Exception as e:
+    logger.debug("MCP tool discovery failed: %s", e)
+

 # =============================================================================
 # Backward-compat constants  (built once after discovery)
--- a/pyproject.toml
+++ b/pyproject.toml
@ -47,6 +47,7 @@ cli = ["simple-term-menu"]
 tts-premium = ["elevenlabs"]
 pty = ["ptyprocess>=0.7.0"]
 honcho = ["honcho-ai>=2.0.1"]
+mcp = ["mcp>=1.2.0"]
 all = [
  "hermes-agent[modal]",
  "hermes-agent[messaging]",
@ -57,6 +58,7 @@ all = [
  "hermes-agent[slack]",
  "hermes-agent[pty]",
  "hermes-agent[honcho]",
+  "hermes-agent[mcp]",
 ]

 [project.scripts]
--- a/skills/mcp/DESCRIPTION.md
+++ b/skills/mcp/DESCRIPTION.md
@ -1,3 +1,3 @@
 ---
-description: Skills for working with MCP (Model Context Protocol) servers, tools, and integrations.
+description: Skills for working with MCP (Model Context Protocol) servers, tools, and integrations. Includes the built-in native MCP client (configure servers in config.yaml for automatic tool discovery) and the mcporter CLI bridge for ad-hoc server interaction.
 ---
--- a/skills/mcp/native-mcp/SKILL.md
+++ b/skills/mcp/native-mcp/SKILL.md
@ -0,0 +1,330 @@
+---
+name: native-mcp
+description: Built-in MCP (Model Context Protocol) client that connects to external MCP servers, discovers their tools, and registers them as native Hermes Agent tools. Supports stdio and HTTP transports with automatic reconnection, security filtering, and zero-config tool injection.
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+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:
+
+```bash
+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:
+
+```yaml
+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)
+
+```yaml
+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)
+
+```yaml
+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.
+
+```yaml
+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 / StreamableHTTP Transport
+
+For remote or shared MCP servers. Requires the `mcp` package to include HTTP client support (`mcp.client.streamable_http`).
+
+```yaml
+mcp_servers:
+  remote_api:
+    url: "https://mcp.example.com/mcp"
+    headers:
+      Authorization: "Bearer sk-..."
+```
+
+If HTTP support is not available in your installed `mcp` version, the server will fail with an ImportError and other servers will continue normally.
+
+## Security
+
+### Environment Variable Filtering
+
+For stdio servers, Hermes does NOT pass your full shell environment to MCP subprocesses. Only safe baseline variables are inherited:
+
+- `PATH`, `HOME`, `USER`, `LANG`, `LC_ALL`, `TERM`, `SHELL`, `TMPDIR`
+- Any `XDG_*` variables
+
+All other environment variables (API keys, tokens, secrets) are excluded unless you explicitly add them via the `env` config key. This prevents accidental credential leakage to untrusted MCP servers.
+
+```yaml
+mcp_servers:
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      # Only this token is passed to the subprocess
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
+```
+
+### Credential Stripping in Error Messages
+
+If an MCP tool call fails, any credential-like patterns in the error message are automatically redacted before being shown to the LLM. This covers:
+
+- GitHub PATs (`ghp_...`)
+- OpenAI-style keys (`sk-...`)
+- Bearer tokens
+- Generic `token=`, `key=`, `API_KEY=`, `password=`, `secret=` patterns
+
+## Troubleshooting
+
+### "MCP SDK not available -- skipping MCP tool discovery"
+
+The `mcp` Python package is not installed. Install it:
+
+```bash
+pip install mcp
+```
+
+### "No MCP servers configured"
+
+No `mcp_servers` key in `~/.hermes/config.yaml`, or it's empty. Add at least one server.
+
+### "Failed to connect to MCP server 'X'"
+
+Common causes:
+- **Command not found**: The `command` binary isn't on PATH. Ensure `npx`, `uvx`, or the relevant command is installed.
+- **Package not found**: For npx servers, the npm package may not exist or may need `-y` in args to auto-install.
+- **Timeout**: The server took too long to start. Increase `connect_timeout`.
+- **Port conflict**: For HTTP servers, the URL may be unreachable.
+
+### "MCP server 'X' requires HTTP transport but mcp.client.streamable_http is not available"
+
+Your `mcp` package version doesn't include HTTP client support. Upgrade:
+
+```bash
+pip install --upgrade mcp
+```
+
+### Tools not appearing
+
+- Check that the server is listed under `mcp_servers` (not `mcp` or `servers`)
+- Ensure the YAML indentation is correct
+- Look at Hermes Agent startup logs for connection messages
+- Tool names are prefixed with `mcp_{server}_{tool}` -- look for that pattern
+
+### Connection keeps dropping
+
+The client retries up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s, capped at 60s). If the server is fundamentally unreachable, it gives up after 5 attempts. Check the server process and network connectivity.
+
+## Examples
+
+### Time Server (uvx)
+
+```yaml
+mcp_servers:
+  time:
+    command: "uvx"
+    args: ["mcp-server-time"]
+```
+
+Registers tools like `mcp_time_get_current_time`.
+
+### Filesystem Server (npx)
+
+```yaml
+mcp_servers:
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
+    timeout: 30
+```
+
+Registers tools like `mcp_filesystem_read_file`, `mcp_filesystem_write_file`, `mcp_filesystem_list_directory`.
+
+### GitHub Server with Authentication
+
+```yaml
+mcp_servers:
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
+    timeout: 60
+```
+
+Registers tools like `mcp_github_list_issues`, `mcp_github_create_pull_request`, etc.
+
+### Remote HTTP Server
+
+```yaml
+mcp_servers:
+  company_api:
+    url: "https://mcp.mycompany.com/v1/mcp"
+    headers:
+      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
+      X-Team-Id: "engineering"
+    timeout: 180
+    connect_timeout: 30
+```
+
+### Multiple Servers
+
+```yaml
+mcp_servers:
+  time:
+    command: "uvx"
+    args: ["mcp-server-time"]
+
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
+
+  company_api:
+    url: "https://mcp.internal.company.com/mcp"
+    headers:
+      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
+    timeout: 300
+```
+
+All tools from all servers are registered and available simultaneously. Each server's tools are prefixed with its name to avoid collisions.
+
+## Notes
+
+- MCP tools are called synchronously from the agent's perspective but run asynchronously on a dedicated background event loop
+- Tool results are returned as JSON with either `{"result": "..."}` or `{"error": "..."}`
+- The native MCP client is independent of `mcporter` -- you can use both simultaneously
+- Server connections are persistent and shared across all conversations in the same agent process
+- Adding or removing servers requires restarting the agent (no hot-reload currently)
--- a/tests/tools/test_mcp_tool.py
+++ b/tests/tools/test_mcp_tool.py
--- a/tools/mcp_tool.py
+++ b/tools/mcp_tool.py
--- a/uv.lock
+++ b/uv.lock
@ -1015,6 +1015,7 @@ all = [
    { name = "discord-py" },
    { name = "elevenlabs" },
    { name = "honcho-ai" },
+    { name = "mcp" },
    { name = "ptyprocess" },
    { name = "pytest" },
    { name = "pytest-asyncio" },
@ -1037,6 +1038,9 @@ dev = [
 honcho = [
    { name = "honcho-ai" },
 ]
+mcp = [
+    { name = "mcp" },
+]
 messaging = [
    { name = "aiohttp" },
    { name = "discord-py" },
@ -1072,6 +1076,7 @@ requires-dist = [
    { name = "hermes-agent", extras = ["cron"], marker = "extra == 'all'" },
    { name = "hermes-agent", extras = ["dev"], marker = "extra == 'all'" },
    { name = "hermes-agent", extras = ["honcho"], marker = "extra == 'all'" },
+    { name = "hermes-agent", extras = ["mcp"], marker = "extra == 'all'" },
    { name = "hermes-agent", extras = ["messaging"], marker = "extra == 'all'" },
    { name = "hermes-agent", extras = ["modal"], marker = "extra == 'all'" },
    { name = "hermes-agent", extras = ["pty"], marker = "extra == 'all'" },
@ -1081,6 +1086,7 @@ requires-dist = [
    { name = "httpx" },
    { name = "jinja2" },
    { name = "litellm", specifier = ">=1.75.5" },
+    { name = "mcp", marker = "extra == 'mcp'", specifier = ">=1.2.0" },
    { name = "openai" },
    { name = "platformdirs" },
    { name = "prompt-toolkit" },
@ -1103,7 +1109,7 @@ requires-dist = [
    { name = "tenacity" },
    { name = "typer" },
 ]
-provides-extras = ["modal", "dev", "messaging", "cron", "slack", "cli", "tts-premium", "pty", "honcho", "all"]
+provides-extras = ["modal", "dev", "messaging", "cron", "slack", "cli", "tts-premium", "pty", "honcho", "mcp", "all"]

 [[package]]
 name = "hf-xet"
@ -1522,6 +1528,31 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/70/bc/6f1c2f612465f5fa89b95bead1f44dcb607670fd42891d8fdcd5d039f4f4/markupsafe-3.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:32001d6a8fc98c8cb5c947787c5d08b0a50663d139f1305bac5885d98d9b40fa", size = 14146, upload-time = "2025-09-27T18:37:28.327Z" },
 ]

+[[package]]
+name = "mcp"
+version = "1.26.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "httpx" },
+    { name = "httpx-sse" },
+    { name = "jsonschema" },
+    { name = "pydantic" },
+    { name = "pydantic-settings" },
+    { name = "pyjwt", extra = ["crypto"] },
+    { name = "python-multipart" },
+    { name = "pywin32", marker = "sys_platform == 'win32'" },
+    { name = "sse-starlette" },
+    { name = "starlette" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
+    { name = "uvicorn", marker = "sys_platform != 'emscripten'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/fc/6d/62e76bbb8144d6ed86e202b5edd8a4cb631e7c8130f3f4893c3f90262b10/mcp-1.26.0.tar.gz", hash = "sha256:db6e2ef491eecc1a0d93711a76f28dec2e05999f93afd48795da1c1137142c66", size = 608005, upload-time = "2026-01-24T19:40:32.468Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fd/d9/eaa1f80170d2b7c5ba23f3b59f766f3a0bb41155fbc32a69adfa1adaaef9/mcp-1.26.0-py3-none-any.whl", hash = "sha256:904a21c33c25aa98ddbeb47273033c435e595bbacfdb177f4bd87f6dceebe1ca", size = 233615, upload-time = "2026-01-24T19:40:30.652Z" },
+]
+
 [[package]]
 name = "mdurl"
 version = "0.1.2"
@ -2114,6 +2145,20 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/36/c7/cfc8e811f061c841d7990b0201912c3556bfeb99cdcb7ed24adc8d6f8704/pydantic_core-2.41.5-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:56121965f7a4dc965bff783d70b907ddf3d57f6eba29b6d2e5dabfaf07799c51", size = 2145302, upload-time = "2025-11-04T13:43:46.64Z" },
 ]

+[[package]]
+name = "pydantic-settings"
+version = "2.13.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pydantic" },
+    { name = "python-dotenv" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/52/6d/fffca34caecc4a3f97bda81b2098da5e8ab7efc9a66e819074a11955d87e/pydantic_settings-2.13.1.tar.gz", hash = "sha256:b4c11847b15237fb0171e1462bf540e294affb9b86db4d9aa5c01730bdbe4025", size = 223826, upload-time = "2026-02-19T13:45:08.055Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/00/4b/ccc026168948fec4f7555b9164c724cf4125eac006e176541483d2c959be/pydantic_settings-2.13.1-py3-none-any.whl", hash = "sha256:d56fd801823dbeae7f0975e1f8c8e25c258eb75d278ea7abb5d9cebb01b56237", size = 58929, upload-time = "2026-02-19T13:45:06.034Z" },
+]
+
 [[package]]
 name = "pygments"
 version = "2.19.2"
@ -2221,6 +2266,28 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/81/c4/34e93fe5f5429d7570ec1fa436f1986fb1f00c3e0f43a589fe2bbcd22c3f/pytz-2025.2-py2.py3-none-any.whl", hash = "sha256:5ddf76296dd8c44c26eb8f4b6f35488f3ccbf6fbbd7adee0b7262d43f0ec2f00", size = 509225, upload-time = "2025-03-25T02:24:58.468Z" },
 ]

+[[package]]
+name = "pywin32"
+version = "311"
+source = { registry = "https://pypi.org/simple" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7b/40/44efbb0dfbd33aca6a6483191dae0716070ed99e2ecb0c53683f400a0b4f/pywin32-311-cp310-cp310-win32.whl", hash = "sha256:d03ff496d2a0cd4a5893504789d4a15399133fe82517455e78bad62efbb7f0a3", size = 8760432, upload-time = "2025-07-14T20:13:05.9Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/bf/360243b1e953bd254a82f12653974be395ba880e7ec23e3731d9f73921cc/pywin32-311-cp310-cp310-win_amd64.whl", hash = "sha256:797c2772017851984b97180b0bebe4b620bb86328e8a884bb626156295a63b3b", size = 9590103, upload-time = "2025-07-14T20:13:07.698Z" },
+    { url = "https://files.pythonhosted.org/packages/57/38/d290720e6f138086fb3d5ffe0b6caa019a791dd57866940c82e4eeaf2012/pywin32-311-cp310-cp310-win_arm64.whl", hash = "sha256:0502d1facf1fed4839a9a51ccbcc63d952cf318f78ffc00a7e78528ac27d7a2b", size = 8778557, upload-time = "2025-07-14T20:13:11.11Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/af/449a6a91e5d6db51420875c54f6aff7c97a86a3b13a0b4f1a5c13b988de3/pywin32-311-cp311-cp311-win32.whl", hash = "sha256:184eb5e436dea364dcd3d2316d577d625c0351bf237c4e9a5fabbcfa5a58b151", size = 8697031, upload-time = "2025-07-14T20:13:13.266Z" },
+    { url = "https://files.pythonhosted.org/packages/51/8f/9bb81dd5bb77d22243d33c8397f09377056d5c687aa6d4042bea7fbf8364/pywin32-311-cp311-cp311-win_amd64.whl", hash = "sha256:3ce80b34b22b17ccbd937a6e78e7225d80c52f5ab9940fe0506a1a16f3dab503", size = 9508308, upload-time = "2025-07-14T20:13:15.147Z" },
+    { url = "https://files.pythonhosted.org/packages/44/7b/9c2ab54f74a138c491aba1b1cd0795ba61f144c711daea84a88b63dc0f6c/pywin32-311-cp311-cp311-win_arm64.whl", hash = "sha256:a733f1388e1a842abb67ffa8e7aad0e70ac519e09b0f6a784e65a136ec7cefd2", size = 8703930, upload-time = "2025-07-14T20:13:16.945Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/ab/01ea1943d4eba0f850c3c61e78e8dd59757ff815ff3ccd0a84de5f541f42/pywin32-311-cp312-cp312-win32.whl", hash = "sha256:750ec6e621af2b948540032557b10a2d43b0cee2ae9758c54154d711cc852d31", size = 8706543, upload-time = "2025-07-14T20:13:20.765Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/a8/a0e8d07d4d051ec7502cd58b291ec98dcc0c3fff027caad0470b72cfcc2f/pywin32-311-cp312-cp312-win_amd64.whl", hash = "sha256:b8c095edad5c211ff31c05223658e71bf7116daa0ecf3ad85f3201ea3190d067", size = 9495040, upload-time = "2025-07-14T20:13:22.543Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/3a/2ae996277b4b50f17d61f0603efd8253cb2d79cc7ae159468007b586396d/pywin32-311-cp312-cp312-win_arm64.whl", hash = "sha256:e286f46a9a39c4a18b319c28f59b61de793654af2f395c102b4f819e584b5852", size = 8710102, upload-time = "2025-07-14T20:13:24.682Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/be/3fd5de0979fcb3994bfee0d65ed8ca9506a8a1260651b86174f6a86f52b3/pywin32-311-cp313-cp313-win32.whl", hash = "sha256:f95ba5a847cba10dd8c4d8fefa9f2a6cf283b8b88ed6178fa8a6c1ab16054d0d", size = 8705700, upload-time = "2025-07-14T20:13:26.471Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/28/e0a1909523c6890208295a29e05c2adb2126364e289826c0a8bc7297bd5c/pywin32-311-cp313-cp313-win_amd64.whl", hash = "sha256:718a38f7e5b058e76aee1c56ddd06908116d35147e133427e59a3983f703a20d", size = 9494700, upload-time = "2025-07-14T20:13:28.243Z" },
+    { url = "https://files.pythonhosted.org/packages/04/bf/90339ac0f55726dce7d794e6d79a18a91265bdf3aa70b6b9ca52f35e022a/pywin32-311-cp313-cp313-win_arm64.whl", hash = "sha256:7b4075d959648406202d92a2310cb990fea19b535c7f4a78d3f5e10b926eeb8a", size = 8709318, upload-time = "2025-07-14T20:13:30.348Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/31/097f2e132c4f16d99a22bfb777e0fd88bd8e1c634304e102f313af69ace5/pywin32-311-cp314-cp314-win32.whl", hash = "sha256:b7a2c10b93f8986666d0c803ee19b5990885872a7de910fc460f9b0c2fbf92ee", size = 8840714, upload-time = "2025-07-14T20:13:32.449Z" },
+    { url = "https://files.pythonhosted.org/packages/90/4b/07c77d8ba0e01349358082713400435347df8426208171ce297da32c313d/pywin32-311-cp314-cp314-win_amd64.whl", hash = "sha256:3aca44c046bd2ed8c90de9cb8427f581c479e594e99b5c0bb19b29c10fd6cb87", size = 9656800, upload-time = "2025-07-14T20:13:34.312Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/d2/21af5c535501a7233e734b8af901574572da66fcc254cb35d0609c9080dd/pywin32-311-cp314-cp314-win_arm64.whl", hash = "sha256:a508e2d9025764a8270f93111a970e1d0fbfc33f4153b388bb649b7eec4f9b42", size = 8932540, upload-time = "2025-07-14T20:13:36.379Z" },
+]
+
 [[package]]
 name = "pyyaml"
 version = "6.0.3"
@ -2639,6 +2706,19 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/e9/44/75a9c9421471a6c4805dbf2356f7c181a29c1879239abab1ea2cc8f38b40/sniffio-1.3.1-py3-none-any.whl", hash = "sha256:2f6da418d1f1e0fddd844478f41680e794e6051915791a034ff65e5f100525a2", size = 10235, upload-time = "2024-02-25T23:20:01.196Z" },
 ]

+[[package]]
+name = "sse-starlette"
+version = "3.3.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "starlette" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5a/9f/c3695c2d2d4ef70072c3a06992850498b01c6bc9be531950813716b426fa/sse_starlette-3.3.2.tar.gz", hash = "sha256:678fca55a1945c734d8472a6cad186a55ab02840b4f6786f5ee8770970579dcd", size = 32326, upload-time = "2026-02-28T11:24:34.36Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/61/28/8cb142d3fe80c4a2d8af54ca0b003f47ce0ba920974e7990fa6e016402d1/sse_starlette-3.3.2-py3-none-any.whl", hash = "sha256:5c3ea3dad425c601236726af2f27689b74494643f57017cafcb6f8c9acfbb862", size = 14270, upload-time = "2026-02-28T11:24:32.984Z" },
+]
+
 [[package]]
 name = "starlette"
 version = "0.52.1"