MCP Tool Integration — Model Context Protocol Setup & Tools

What Is MCP?

Model Context Protocol is Anthropic's open standard for giving AI models a consistent way to call external tools. An MCP server exposes a set of tools (functions with typed inputs and outputs) over a standard transport (stdio, HTTP, or WebSocket). The model calls tools by name; the MCP server executes them and returns structured results.

For Hermes, MCP tools serve the same purpose as OpenClaw skills — but with a richer protocol: tools can have streaming responses, resource subscriptions, and stateful sessions. Because MCP is an open standard, tools built for Claude Desktop, Cursor, or any MCP-compatible client also work in Hermes.

Connecting MCP Servers — v0.9.x (Current)

In v0.9.x, MCP servers are connected via the adapter layer. Each server is defined in hermes.json under tools.mcp:

{
  "tools": {
    "mcp": {
      "servers": [
        {
          "name":      "filesystem",
          "transport": "stdio",
          "command":   "npx",
          "args":      ["-y", "@modelcontextprotocol/server-filesystem", "~/.hermes/workspace"]
        },
        {
          "name":      "github",
          "transport": "stdio",
          "command":   "npx",
          "args":      ["-y", "@modelcontextprotocol/server-github"],
          "env": {
            "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
          }
        },
        {
          "name":      "brave-search",
          "transport": "stdio",
          "command":   "npx",
          "args":      ["-y", "@modelcontextprotocol/server-brave-search"],
          "env": {
            "BRAVE_API_KEY": "${BRAVE_API_KEY}"
          }
        }
      ]
    }
  }
}

After updating the config, reload Hermes:

hermes config reload

# Verify tools are available
hermes tools list
# filesystem   mcp    read_file, write_file, list_directory, search_files
# github       mcp    get_issue, list_issues, create_issue, get_pr, list_prs
# brave-search mcp    search, local_search

Native MCP — v1.0 Preview

If you're running a v1.0 preview build, the config is simpler — MCP servers are discovered automatically once connected:

{
  "tools": {
    "mcp": {
      "autoDiscover": true,
      "servers": [
        {
          "name":      "github",
          "transport": "stdio",
          "command":   "npx",
          "args":      ["-y", "@modelcontextprotocol/server-github"],
          "env":       { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
        }
      ]
    }
  }
}

# In v1.0, tools are auto-discovered and listed:
hermes tools list --verbose
# github  mcp  [auto-discovered]
#   get_file_contents     — Read file content from GitHub repo
#   push_files            — Push multiple files in a single commit
#   create_issue          — Create a GitHub issue
#   list_issues           — List issues with filtering
#   create_pull_request   — Open a new PR
#   ... (28 more tools)

MCP Tool Authorisation

Before Hermes can use MCP tools in tasks, you must authorise them. This prevents a task description from accidentally triggering destructive tool calls:

# Authorise all tools from a server (grants read + write)
hermes tools authorise github

# Authorise specific tools only (recommended for write/delete operations)
hermes tools authorise github --tools "get_issue,list_issues,get_file_contents"
# Write and delete operations remain unauthorised — must be added explicitly

# View current authorisations
hermes tools authorise list
# github      mcp    get_issue ✓  list_issues ✓  get_file_contents ✓
#                    push_files ✗  create_issue ✗  (not authorised)

# Revoke a tool
hermes tools authorise revoke github --tool "push_files"

Popular MCP Servers for Hermes

Install them all with npx — no global install needed:

# They're run on-demand by Hermes; npx fetches automatically
# Just add the server to your hermes.json and reload

The full MCP server registry: modelcontextprotocol.io/servers

Using MCP Tools in Tasks

Once authorised, MCP tools are available automatically — Hermes decides when to use them based on the task description. You don't call tools explicitly in most cases:

# Hermes will use the github MCP server automatically:
hermes run "List all open issues in my Atlas repo that are labelled 'bug' and summarise them"

# Hermes will use brave-search automatically:
hermes run "Research the top 5 vector database options in 2026, compare on cost and query latency"

# Hermes will use filesystem automatically:
hermes run "Read all .md files in my workspace/notes/ directory and create a table of contents"

For tasks where you want to specify which tools to use:

hermes run \
  --tools "github,filesystem" \
  "Pull all open PRs from the Atlas repo, read the diff for each, and write a review summary to workspace/pr-review.md"

Writing a Custom MCP Server for Hermes

Any MCP server works with Hermes. Here's a minimal custom server in Node.js that exposes a tool to check a website's status:

// ~/my-mcp-tools/status-check.js
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "status-check", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "check_status",
    description: "Check if a URL returns HTTP 200",
    inputSchema: {
      type: "object",
      properties: {
        url: { type: "string", description: "URL to check" }
      },
      required: ["url"]
    }
  }]
}));

server.setRequestHandler("tools/call", async (request) => {
  const { url } = request.params.arguments;
  try {
    const res = await fetch(url, { method: "HEAD", signal: AbortSignal.timeout(5000) });
    return {
      content: [{ type: "text", text: `${url} — ${res.status} ${res.statusText}` }]
    };
  } catch (e) {
    return {
      content: [{ type: "text", text: `${url} — UNREACHABLE: ${e.message}` }],
      isError: true
    };
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);

Register it in Hermes:

{
  "tools": {
    "mcp": {
      "servers": [
        {
          "name":      "status-check",
          "transport": "stdio",
          "command":   "node",
          "args":      ["/home/YOU/my-mcp-tools/status-check.js"]
        }
      ]
    }
  }
}

hermes config reload
hermes tools authorise status-check
hermes run "Check if these URLs are up: https://example.com, https://api.example.com/health"

MCP Tools Inside Long-Running Tasks

MCP tools work across the full lifecycle of a long-running task. At each step, Hermes spins up the required MCP servers, executes the step, and the servers shut down until the next step. In v0.9.x this spin-up adds ~1–2 seconds per step. In v1.0, server connections are persistent across steps (much faster).

Tool outputs from one step are stored in episode memory and available to all subsequent steps in the same task — Hermes doesn't call the same tool twice for the same data unless the task explicitly requires a fresh fetch.

# Example: a multi-step task that uses tools at each step
hermes run --deadline "friday 5pm" "$(cat <<'EOF'
1. Use GitHub to list all open issues in Atlas repo
2. Use brave-search to research solutions for the top 3 bugs
3. For each bug, write a draft fix plan to workspace/fix-plans/
4. Use GitHub to create a comment on each issue with a link to the plan file
EOF
)"