Overview

FastMCP (v3.1.0, Apache-2.0, 23.3k stars, ~1M downloads/day) is the standard Python framework for building Model Context Protocol applications. It powers approximately 70% of MCP servers across all languages. FastMCP 1.0 was incorporated into the official MCP Python SDK in 2024, and the standalone project has since evolved to v3 with server composition, proxying, transforms, apps, and a rich client API.

Hermes Agent currently connects to MCP servers as a client (tools/mcp_tool.py, ~1050 lines). This feature proposes the reverse — exposing Hermes Agent's own tools as an MCP server using FastMCP, so that other AI clients and agents can use Hermes's tools. This would make Hermes a first-class citizen in the MCP ecosystem, enabling interop with Claude Desktop, Cursor, VS Code Copilot, Windsurf, and any other MCP-compatible client.

Research source: FastMCP Documentation and GitHub repo

Research Findings

How FastMCP Works

FastMCP is organized around three pillars:

1. Servers — Expose Python functions as MCP tools

from fastmcp import FastMCP

mcp = FastMCP("HermesTools")

@mcp.tool
def search_files(pattern: str, path: str = ".") -> str:
    """Search file contents using regex"""
    # ... implementation
    return results

FastMCP auto-generates JSON schemas from type annotations, handles validation, supports async, and manages transport negotiation (stdio, HTTP, SSE).

2. Clients — Connect to any MCP server

from fastmcp import Client

async with Client("http://localhost:8000/mcp") as client:
    tools = await client.list_tools()
    result = await client.call_tool("search_files", {"pattern": "TODO"})

Supports auto-detecting transports, config-based multi-server, tool transformations (rename, filter, modify arguments), and OAuth authentication.

3. Composition — Combine and proxy servers

main = FastMCP("Main")
main.mount(sub_server, namespace="api")
main.mount(create_proxy("http://remote.com/mcp"), namespace="remote")

Live-linking, namespaced tools, transport bridging (stdio↔HTTP), and recursive tag filtering.

Key Advanced Features

FastMCP's Client vs. Hermes's Current MCP Client

Hermes's mcp_tool.py is a well-crafted ~1050-line implementation using the raw mcp SDK. It handles:

• ✅ Stdio and HTTP transports
• ✅ Auto-reconnection with exponential backoff
• ✅ Tool discovery → registry integration
• ✅ Resources and prompts
• ✅ Security (env filtering, credential stripping)
• ✅ Parallel discovery, configurable timeouts
• ✅ Dynamic toolset injection

FastMCP's Client offers comparable functionality with:

• Config-based multi-server (same mcpServers dict format)
• Auto-detecting transports
• Tool transformations (rename, filter, hide arguments)
• OAuth authentication handling
• In-memory transport for testing
• BUT: would need custom integration with Hermes's registry

The current client implementation is stable and purpose-built. Replacing it is not the priority — the server side is the bigger opportunity.

Current State in Hermes Agent

MCP Client (what we have)

• tools/mcp_tool.py — Full MCP client with stdio/HTTP, reconnection, security
• docs/mcp.md — Comprehensive docs with config translation guide
• Config: mcp_servers key in ~/.hermes/config.yaml
• Dependency: mcp>=1.2.0 (raw SDK, optional)
• Skill: mcporter for CLI-based MCP tool calling

MCP Server (what we lack)

• No way to expose Hermes tools to other clients
• Other agents/clients cannot call search_files, terminal, web_search etc.
• Hermes is an MCP consumer only, not a provider

Integration Points

• tools/registry.py — Central tool registry with schemas, handlers, check functions
• toolsets.py — Tool groupings (hermes-cli, hermes-telegram, etc.)
• model_tools.py — Tool orchestration and discovery
• hermes_cli/main.py — CLI entry point (would host the server command)

Implementation Plan

Skill vs. Tool Classification

This should be a core codebase feature because:

• It requires deep integration with the tool registry and toolset system
• It needs the FastMCP library as a dependency (not just CLI wrapping)
• It involves a new runtime mode for the agent (serving, not just consuming)
• The server must dynamically reflect Hermes's registered tools

What We'd Need

1. FastMCP dependency — Add fastmcp>=3.0.0 as an optional dependency (pip install hermes-agent[mcp-server])
2. Tool registry → MCP adapter — Bridge that reads Hermes's tool registry and exposes each tool as a FastMCP tool
3. Server command — hermes serve-mcp to start Hermes as an MCP server
4. Toolset → Tag mapping — Map Hermes toolsets to FastMCP tags for filtering
5. Security layer — Auth for HTTP transport, tool allowlisting

Phased Rollout

Phase 1: Basic MCP server mode

• New CLI command: hermes serve-mcp [--transport stdio|http] [--port 8000]
• Reads all registered tools from the Hermes registry
• Wraps each as a FastMCP tool with proper schemas
• Supports stdio (for Claude Desktop, Cursor) and HTTP (for remote access)
• Config: mcp_server key in config.yaml (enable/disable, allowed tools, port)
• Deliverable: Other MCP clients can call Hermes tools

Phase 2: Selective exposure and security

• Toolset-based filtering — only expose specific toolsets (e.g., file, web, not terminal)
• Tag-based visibility using FastMCP's transform system
• OAuth/token auth for HTTP transport
• Tool allowlist/denylist in config
• Rate limiting and usage logging
• Deliverable: Secure, production-ready MCP server

Phase 3: Advanced features and client improvements

• Composition: Mount external MCP servers through Hermes (unified tool proxy)
• Tool transforms: Rename/modify tools exposed to external clients
• Consider FastMCP Client: Evaluate replacing mcp_tool.py with FastMCP's Client for simpler code and additional features (transforms, OAuth)
• Apps: Rich interactive output from Hermes tools
• Install command: hermes install-mcp claude-desktop to auto-configure clients
• Deliverable: Hermes as a full MCP hub (consuming + serving + proxying)

Pros & Cons

Pros

• Ecosystem interop — Any MCP client (Claude Desktop, Cursor, VS Code, Windsurf, custom) can use Hermes tools
• Agent-to-agent — Other AI agents can leverage Hermes's tools without reimplementing them
• Two-way bridge — Hermes already consumes MCP; serving completes the picture
• Low friction — FastMCP makes server creation trivial (~50 lines for the adapter)
• Standards-based — MCP is backed by Anthropic and widely adopted; not a proprietary protocol
• Free hosting — Prefect Horizon offers free FastMCP hosting
• Apache-2.0 — No license conflict with Hermes's MIT license

Cons / Risks

• New dependency — FastMCP is a substantial package (pulls in Starlette, uvicorn for HTTP)
• Security surface — Exposing tools (especially terminal) to external clients requires careful access control
• Maintenance burden — Must keep the registry↔FastMCP adapter in sync as tools change
• Scope creep — "Hermes as MCP hub" could become an unbounded project
• Performance — Tool calls through MCP add latency vs. direct in-process calls

Open Questions

• Which tools should be exposed by default? All tools, or a safe subset (web, file, search only)?
• Should terminal ever be exposed via MCP? If so, under what security constraints?
• Should the MCP server run as a separate process or within the main Hermes agent process?
• Should we support the fastmcp install command to auto-configure Claude Desktop/Cursor?
• Is there demand from users to use Hermes tools from other clients?

References

• FastMCP Documentation
• FastMCP GitHub (Apache-2.0, 23.3k stars)
• Model Context Protocol — Official MCP spec
• Hermes MCP Client — Existing implementation
• Hermes MCP Docs — Current MCP documentation
• FastMCP Composition — Server mounting/namespacing
• FastMCP Transforms — Tool pipeline middleware
• FastMCP CLI — run, inspect, install, discover commands