[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6DCGXH77DCNTQF7Z2GX17F9":3,"skill-same:01M6DCGXH77DCNTQF7Z2GX17F9":72},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":37,"linkOnly":38,"markdownContent":39,"markdownBody":40,"frontMatter":41,"refName":50,"commitSha":51,"skillDirectory":52,"forksCount":53,"repositoryHtmlUrl":54,"repositoryHomepageUrl":6,"ownerHtmlUrl":55,"ownerBlogUrl":6,"ownerDescription":56,"updatedAt":57,"install":58,"resources":71},"01M6DCGXH77DCNTQF7Z2GX17F9","native-mcp",null,"MCP client: connect servers, register tools (stdio\u002FHTTP).","zapabob\u002FSkills","zapabob","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F130830376?v=4","01M6DBMYZAGRTFQDSQYW3W764P","峯岸 亮","01M6DBMZ3GKDSJ01NZ9XTZD7JD",2,"MIT","https:\u002F\u002Fgithub.com\u002Fzapabob\u002FSkills\u002Fblob\u002Fmain\u002Farchive\u002Fskill-md-reviewed\u002Fsha256\u002F14\u002F14d2512c69908a8dafdf1a0a24d327597d0f9e59919169180548129de849554d\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36],"MCP","native mcp","macos","mcporter","linux","windows","http","connect","mcp client","Tools","integrations","hermes","hermes agent","2026-11-10 10:12:30",false,"---\r\nname: native-mcp\r\ndescription: \"MCP client: connect servers, register tools (stdio\u002FHTTP).\"\r\nversion: 1.0.0\r\nauthor: Hermes Agent\r\nlicense: MIT\r\nplatforms: [linux, macos, windows]\r\nmetadata:\r\n  hermes:\r\n    tags: [MCP, Tools, Integrations]\r\n    related_skills: [mcporter]\r\n---\r\n\r\n# Native MCP Client\r\n\r\nHermes 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.\r\n\r\n## When to Use\r\n\r\nUse this whenever you want to:\r\n- Connect to MCP servers and use their tools from within Hermes Agent\r\n- Add external capabilities (filesystem access, GitHub, databases, APIs) via MCP\r\n- Run local stdio-based MCP servers (npx, uvx, or any command)\r\n- Connect to remote HTTP\u002FStreamableHTTP MCP servers\r\n- Have MCP tools auto-discovered and available in every conversation\r\n\r\nFor ad-hoc, one-off MCP tool calls from the terminal without configuring anything, see the `mcporter` skill instead.\r\n\r\n## Prerequisites\r\n\r\n- **mcp Python package** -- optional dependency; install with `pip install mcp`. If not installed, MCP support is silently disabled.\r\n- **Node.js** -- required for `npx`-based MCP servers (most community servers)\r\n- **uv** -- required for `uvx`-based MCP servers (Python-based servers)\r\n\r\nInstall the MCP SDK:\r\n\r\n```bash\r\npip install mcp\r\n# or, if using uv:\r\nuv pip install mcp\r\n```\r\n\r\n## Quick Start\r\n\r\nAdd MCP servers to `~\u002F.hermes\u002Fconfig.yaml` under the `mcp_servers` key:\r\n\r\n```yaml\r\nmcp_servers:\r\n  time:\r\n    command: \"uvx\"\r\n    args: [\"mcp-server-time\"]\r\n```\r\n\r\nRestart Hermes Agent. On startup it will:\r\n1. Connect to the server\r\n2. Discover available tools\r\n3. Register them with the prefix `mcp_time_*`\r\n4. Inject them into all platform toolsets\r\n\r\nYou can then use the tools naturally -- just ask the agent to get the current time.\r\n\r\n## Configuration Reference\r\n\r\nEach entry under `mcp_servers` is a server name mapped to its config. There are two transport types: **stdio** (command-based) and **HTTP** (url-based).\r\n\r\n### Stdio Transport (command + args)\r\n\r\n```yaml\r\nmcp_servers:\r\n  server_name:\r\n    command: \"npx\"             # (required) executable to run\r\n    args: [\"-y\", \"pkg-name\"]   # (optional) command arguments, default: []\r\n    env:                       # (optional) environment variables for the subprocess\r\n      SOME_API_KEY: \"value\"\r\n    timeout: 120               # (optional) per-tool-call timeout in seconds, default: 120\r\n    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60\r\n```\r\n\r\n### HTTP Transport (url)\r\n\r\n```yaml\r\nmcp_servers:\r\n  server_name:\r\n    url: \"https:\u002F\u002Fmy-server.example.com\u002Fmcp\"   # (required) server URL\r\n    headers:                                     # (optional) HTTP headers\r\n      Authorization: \"Bearer sk-...\"\r\n    timeout: 180               # (optional) per-tool-call timeout in seconds, default: 120\r\n    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60\r\n```\r\n\r\n### All Config Options\r\n\r\n| Option            | Type   | Default | Description                                       |\r\n|-------------------|--------|---------|---------------------------------------------------|\r\n| `command`         | string | --      | Executable to run (stdio transport, required)     |\r\n| `args`            | list   | `[]`    | Arguments passed to the command                   |\r\n| `env`             | dict   | `{}`    | Extra environment variables for the subprocess    |\r\n| `url`             | string | --      | Server URL (HTTP transport, required)             |\r\n| `headers`         | dict   | `{}`    | HTTP headers sent with every request              |\r\n| `timeout`         | int    | `120`   | Per-tool-call timeout in seconds                  |\r\n| `connect_timeout` | int    | `60`    | Timeout for initial connection and discovery      |\r\n\r\nNote: A server config must have either `command` (stdio) or `url` (HTTP), not both.\r\n\r\n## How It Works\r\n\r\n### Startup Discovery\r\n\r\nWhen Hermes Agent starts, `discover_mcp_tools()` is called during tool initialization:\r\n\r\n1. Reads `mcp_servers` from `~\u002F.hermes\u002Fconfig.yaml`\r\n2. For each server, spawns a connection in a dedicated background event loop\r\n3. Initializes the MCP session and calls `list_tools()` to discover available tools\r\n4. Registers each tool in the Hermes tool registry\r\n\r\n### Tool Naming Convention\r\n\r\nMCP tools are registered with the naming pattern:\r\n\r\n```\r\nmcp_{server_name}_{tool_name}\r\n```\r\n\r\nHyphens and dots in names are replaced with underscores for LLM API compatibility.\r\n\r\nExamples:\r\n- Server `filesystem`, tool `read_file` → `mcp_filesystem_read_file`\r\n- Server `github`, tool `list-issues` → `mcp_github_list_issues`\r\n- Server `my-api`, tool `fetch.data` → `mcp_my_api_fetch_data`\r\n\r\n### Auto-Injection\r\n\r\nAfter 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.\r\n\r\n### Connection Lifecycle\r\n\r\n- Each server runs as a long-lived asyncio Task in a background daemon thread\r\n- Connections persist for the lifetime of the agent process\r\n- If a connection drops, automatic reconnection with exponential backoff kicks in (up to 5 retries, max 60s backoff)\r\n- On agent shutdown, all connections are gracefully closed\r\n\r\n### Idempotency\r\n\r\n`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.\r\n\r\n## Transport Types\r\n\r\n### Stdio Transport\r\n\r\nThe most common transport. Hermes launches the MCP server as a subprocess and communicates over stdin\u002Fstdout.\r\n\r\n```yaml\r\nmcp_servers:\r\n  filesystem:\r\n    command: \"npx\"\r\n    args: [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\", \"\u002Fhome\u002Fuser\u002Fprojects\"]\r\n```\r\n\r\nThe subprocess inherits a **filtered** environment (see Security section below) plus any variables you specify in `env`.\r\n\r\n### HTTP \u002F StreamableHTTP Transport\r\n\r\nFor remote or shared MCP servers. Requires the `mcp` package to include HTTP client support (`mcp.client.streamable_http`).\r\n\r\n```yaml\r\nmcp_servers:\r\n  remote_api:\r\n    url: \"https:\u002F\u002Fmcp.example.com\u002Fmcp\"\r\n    headers:\r\n      Authorization: \"Bearer sk-...\"\r\n```\r\n\r\nIf HTTP support is not available in your installed `mcp` version, the server will fail with an ImportError and other servers will continue normally.\r\n\r\n## Security\r\n\r\n### Environment Variable Filtering\r\n\r\nFor stdio servers, Hermes does NOT pass your full shell environment to MCP subprocesses. Only safe baseline variables are inherited:\r\n\r\n- `PATH`, `HOME`, `USER`, `LANG`, `LC_ALL`, `TERM`, `SHELL`, `TMPDIR`\r\n- Any `XDG_*` variables\r\n\r\nAll 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.\r\n\r\n```yaml\r\nmcp_servers:\r\n  github:\r\n    command: \"npx\"\r\n    args: [\"-y\", \"@modelcontextprotocol\u002Fserver-github\"]\r\n    env:\r\n      # Only this token is passed to the subprocess\r\n      GITHUB_PERSONAL_ACCESS_TOKEN: \"ghp_...\"\r\n```\r\n\r\n### Credential Stripping in Error Messages\r\n\r\nIf an MCP tool call fails, any credential-like patterns in the error message are automatically redacted before being shown to the LLM. This covers:\r\n\r\n- GitHub PATs (`ghp_...`)\r\n- OpenAI-style keys (`sk-...`)\r\n- Bearer tokens\r\n- Generic `token=`, `key=`, `API_KEY=`, `password=`, `secret=` patterns\r\n\r\n## Troubleshooting\r\n\r\n### \"MCP SDK not available -- skipping MCP tool discovery\"\r\n\r\nThe `mcp` Python package is not installed. Install it:\r\n\r\n```bash\r\npip install mcp\r\n```\r\n\r\n### \"No MCP servers configured\"\r\n\r\nNo `mcp_servers` key in `~\u002F.hermes\u002Fconfig.yaml`, or it's empty. Add at least one server.\r\n\r\n### \"Failed to connect to MCP server 'X'\"\r\n\r\nCommon causes:\r\n- **Command not found**: The `command` binary isn't on PATH. Ensure `npx`, `uvx`, or the relevant command is installed.\r\n- **Package not found**: For npx servers, the npm package may not exist or may need `-y` in args to auto-install.\r\n- **Timeout**: The server took too long to start. Increase `connect_timeout`.\r\n- **Port conflict**: For HTTP servers, the URL may be unreachable.\r\n\r\n### \"MCP server 'X' requires HTTP transport but mcp.client.streamable_http is not available\"\r\n\r\nYour `mcp` package version doesn't include HTTP client support. Upgrade:\r\n\r\n```bash\r\npip install --upgrade mcp\r\n```\r\n\r\n### Tools not appearing\r\n\r\n- Check that the server is listed under `mcp_servers` (not `mcp` or `servers`)\r\n- Ensure the YAML indentation is correct\r\n- Look at Hermes Agent startup logs for connection messages\r\n- Tool names are prefixed with `mcp_{server}_{tool}` -- look for that pattern\r\n\r\n### Connection keeps dropping\r\n\r\nThe 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.\r\n\r\n## Examples\r\n\r\n### CodeGraph MCP + VR\u002FWebXR workflow\r\n\r\nWhen adding a source-code graph server such as CodeGraph, use the workflow in `references\u002Fcodegraph-mcp-vr.md`: install\u002Fbuild the CLI, enable a stable `mcp_servers.codegraph` entry, restart Hermes for discovery, verify connected tools, index the target repository, then verify any WebXR\u002FVR viewer via `\u002Fhealthz` and `\u002Fgraph.json` before reporting URLs. Treat dependency audit remediation as a separate change unless the user explicitly asks to fix it.\r\n\r\n### Time Server (uvx)\r\n\r\n```yaml\r\nmcp_servers:\r\n  time:\r\n    command: \"uvx\"\r\n    args: [\"mcp-server-time\"]\r\n```\r\n\r\nRegisters tools like `mcp_time_get_current_time`.\r\n\r\n### Filesystem Server (npx)\r\n\r\n```yaml\r\nmcp_servers:\r\n  filesystem:\r\n    command: \"npx\"\r\n    args: [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\", \"\u002Fhome\u002Fuser\u002Fdocuments\"]\r\n    timeout: 30\r\n```\r\n\r\nRegisters tools like `mcp_filesystem_read_file`, `mcp_filesystem_write_file`, `mcp_filesystem_list_directory`.\r\n\r\n### GitHub Server with Authentication\r\n\r\n```yaml\r\nmcp_servers:\r\n  github:\r\n    command: \"npx\"\r\n    args: [\"-y\", \"@modelcontextprotocol\u002Fserver-github\"]\r\n    env:\r\n      GITHUB_PERSONAL_ACCESS_TOKEN:\"[REDACTED]\"\r\n    timeout: 60\r\n```\r\n\r\nRegisters tools like `mcp_github_list_issues`, `mcp_github_create_pull_request`, etc.\r\n\r\n### Remote HTTP Server\r\n\r\n```yaml\r\nmcp_servers:\r\n  company_api:\r\n    url: \"https:\u002F\u002Fmcp.mycompany.com\u002Fv1\u002Fmcp\"\r\n    headers:\r\n      Authorization: \"Bearer [REDACTED_TOKEN]\"\r\n      X-Team-Id: \"engineering\"\r\n    timeout: 180\r\n    connect_timeout: 30\r\n```\r\n\r\n### Multiple Servers\r\n\r\n```yaml\r\nmcp_servers:\r\n  time:\r\n    command: \"uvx\"\r\n    args: [\"mcp-server-time\"]\r\n\r\n  filesystem:\r\n    command: \"npx\"\r\n    args: [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\", \"\u002Ftmp\"]\r\n\r\n  github:\r\n    command: \"npx\"\r\n    args: [\"-y\", \"@modelcontextprotocol\u002Fserver-github\"]\r\n    env:\r\n      GITHUB_PERSONAL_ACCESS_TOKEN:\"[REDACTED]\"\r\n\r\n  company_api:\r\n    url: \"https:\u002F\u002Fmcp.internal.company.com\u002Fmcp\"\r\n    headers:\r\n      Authorization: \"Bearer [REDACTED_TOKEN]\"\r\n    timeout: 300\r\n```\r\n\r\nAll tools from all servers are registered and available simultaneously. Each server's tools are prefixed with its name to avoid collisions.\r\n\r\n## Sampling (Server-Initiated LLM Requests)\r\n\r\nHermes supports MCP's `sampling\u002FcreateMessage` capability — MCP servers can request LLM completions through the agent during tool execution. This enables agent-in-the-loop workflows (data analysis, content generation, decision-making).\r\n\r\nSampling is **enabled by default**. Configure per server:\r\n\r\n```yaml\r\nmcp_servers:\r\n  my_server:\r\n    command: \"npx\"\r\n    args: [\"-y\", \"my-mcp-server\"]\r\n    sampling:\r\n      enabled: true           # default: true\r\n      model: \"gemini-3-flash\" # model override (optional)\r\n      max_tokens_cap: 4096    # max tokens per request\r\n      timeout: 30             # LLM call timeout (seconds)\r\n      max_rpm: 10             # max requests per minute\r\n      allowed_models: []      # model whitelist (empty = all)\r\n      max_tool_rounds: 5      # tool loop limit (0 = disable)\r\n      log_level: \"info\"       # audit verbosity\r\n```\r\n\r\nServers can also include `tools` in sampling requests for multi-turn tool-augmented workflows. The `max_tool_rounds` config prevents infinite tool loops. Per-server audit metrics (requests, errors, tokens, tool use count) are tracked via `get_mcp_status()`.\r\n\r\nDisable sampling for untrusted servers with `sampling: { enabled: false }`.\r\n\r\n## Notes\r\n\r\n- MCP tools are called synchronously from the agent's perspective but run asynchronously on a dedicated background event loop\r\n- Tool results are returned as JSON with either `{\"result\": \"...\"}` or `{\"error\": \"...\"}`\r\n- The native MCP client is independent of `mcporter` -- you can use both simultaneously\r\n- Server connections are persistent and shared across all conversations in the same agent process\r\n- Adding or removing servers requires restarting the agent (no hot-reload currently)\r\n","# Native MCP Client\r\n\r\nHermes 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.\r\n\r\n## When to Use\r\n\r\nUse this whenever you want to:\r\n- Connect to MCP servers and use their tools from within Hermes Agent\r\n- Add external capabilities (filesystem access, GitHub, databases, APIs) via MCP\r\n- Run local stdio-based MCP servers (npx, uvx, or any command)\r\n- Connect to remote HTTP\u002FStreamableHTTP MCP servers\r\n- Have MCP tools auto-discovered and available in every conversation\r\n\r\nFor ad-hoc, one-off MCP tool calls from the terminal without configuring anything, see the `mcporter` skill instead.\r\n\r\n## Prerequisites\r\n\r\n- **mcp Python package** -- optional dependency; install with `pip install mcp`. If not installed, MCP support is silently disabled.\r\n- **Node.js** -- required for `npx`-based MCP servers (most community servers)\r\n- **uv** -- required for `uvx`-based MCP servers (Python-based servers)\r\n\r\nInstall the MCP SDK:\r\n\r\n```bash\r\npip install mcp\r\n# or, if using uv:\r\nuv pip install mcp\r\n```\r\n\r\n## Quick Start\r\n\r\nAdd MCP servers to `~\u002F.hermes\u002Fconfig.yaml` under the `mcp_servers` key:\r\n\r\n```yaml\r\nmcp_servers:\r\n  time:\r\n    command: \"uvx\"\r\n    args: [\"mcp-server-time\"]\r\n```\r\n\r\nRestart Hermes Agent. On startup it will:\r\n1. Connect to the server\r\n2. Discover available tools\r\n3. Register them with the prefix `mcp_time_*`\r\n4. Inject them into all platform toolsets\r\n\r\nYou can then use the tools naturally -- just ask the agent to get the current time.\r\n\r\n## Configuration Reference\r\n\r\nEach entry under `mcp_servers` is a server name mapped to its config. There are two transport types: **stdio** (command-based) and **HTTP** (url-based).\r\n\r\n### Stdio Transport (command + args)\r\n\r\n```yaml\r\nmcp_servers:\r\n  server_name:\r\n    command: \"npx\"             # (required) executable to run\r\n    args: [\"-y\", \"pkg-name\"]   # (optional) command arguments, default: []\r\n    env:                       # (optional) environment variables for the subprocess\r\n      SOME_API_KEY: \"value\"\r\n    timeout: 120               # (optional) per-tool-call timeout in seconds, default: 120\r\n    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60\r\n```\r\n\r\n### HTTP Transport (url)\r\n\r\n```yaml\r\nmcp_servers:\r\n  server_name:\r\n    url: \"https:\u002F\u002Fmy-server.example.com\u002Fmcp\"   # (required) server URL\r\n    headers:                                     # (optional) HTTP headers\r\n      Authorization: \"Bearer sk-...\"\r\n    timeout: 180               # (optional) per-tool-call timeout in seconds, default: 120\r\n    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60\r\n```\r\n\r\n### All Config Options\r\n\r\n| Option            | Type   | Default | Description                                       |\r\n|-------------------|--------|---------|---------------------------------------------------|\r\n| `command`         | string | --      | Executable to run (stdio transport, required)     |\r\n| `args`            | list   | `[]`    | Arguments passed to the command                   |\r\n| `env`             | dict   | `{}`    | Extra environment variables for the subprocess    |\r\n| `url`             | string | --      | Server URL (HTTP transport, required)             |\r\n| `headers`         | dict   | `{}`    | HTTP headers sent with every request              |\r\n| `timeout`         | int    | `120`   | Per-tool-call timeout in seconds                  |\r\n| `connect_timeout` | int    | `60`    | Timeout for initial connection and discovery      |\r\n\r\nNote: A server config must have either `command` (stdio) or `url` (HTTP), not both.\r\n\r\n## How It Works\r\n\r\n### Startup Discovery\r\n\r\nWhen Hermes Agent starts, `discover_mcp_tools()` is called during tool initialization:\r\n\r\n1. Reads `mcp_servers` from `~\u002F.hermes\u002Fconfig.yaml`\r\n2. For each server, spawns a connection in a dedicated background event loop\r\n3. Initializes the MCP session and calls `list_tools()` to discover available tools\r\n4. Registers each tool in the Hermes tool registry\r\n\r\n### Tool Naming Convention\r\n\r\nMCP tools are registered with the naming pattern:\r\n\r\n```\r\nmcp_{server_name}_{tool_name}\r\n```\r\n\r\nHyphens and dots in names are replaced with underscores for LLM API compatibility.\r\n\r\nExamples:\r\n- Server `filesystem`, tool `read_file` → `mcp_filesystem_read_file`\r\n- Server `github`, tool `list-issues` → `mcp_github_list_issues`\r\n- Server `my-api`, tool `fetch.data` → `mcp_my_api_fetch_data`\r\n\r\n### Auto-Injection\r\n\r\nAfter 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.\r\n\r\n### Connection Lifecycle\r\n\r\n- Each server runs as a long-lived asyncio Task in a background daemon thread\r\n- Connections persist for the lifetime of the agent process\r\n- If a connection drops, automatic reconnection with exponential backoff kicks in (up to 5 retries, max 60s backoff)\r\n- On agent shutdown, all connections are gracefully closed\r\n\r\n### Idempotency\r\n\r\n`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.\r\n\r\n## Transport Types\r\n\r\n### Stdio Transport\r\n\r\nThe most common transport. Hermes launches the MCP server as a subprocess and communicates over stdin\u002Fstdout.\r\n\r\n```yaml\r\nmcp_servers:\r\n  filesystem:\r\n    command: \"npx\"\r\n    args: [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\", \"\u002Fhome\u002Fuser\u002Fprojects\"]\r\n```\r\n\r\nThe subprocess inherits a **filtered** environment (see Security section below) plus any variables you specify in `env`.\r\n\r\n### HTTP \u002F StreamableHTTP Transport\r\n\r\nFor remote or shared MCP servers. Requires the `mcp` package to include HTTP client support (`mcp.client.streamable_http`).\r\n\r\n```yaml\r\nmcp_servers:\r\n  remote_api:\r\n    url: \"https:\u002F\u002Fmcp.example.com\u002Fmcp\"\r\n    headers:\r\n      Authorization: \"Bearer sk-...\"\r\n```\r\n\r\nIf HTTP support is not available in your installed `mcp` version, the server will fail with an ImportError and other servers will continue normally.\r\n\r\n## Security\r\n\r\n### Environment Variable Filtering\r\n\r\nFor stdio servers, Hermes does NOT pass your full shell environment to MCP subprocesses. Only safe baseline variables are inherited:\r\n\r\n- `PATH`, `HOME`, `USER`, `LANG`, `LC_ALL`, `TERM`, `SHELL`, `TMPDIR`\r\n- Any `XDG_*` variables\r\n\r\nAll 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.\r\n\r\n```yaml\r\nmcp_servers:\r\n  github:\r\n    command: \"npx\"\r\n    args: [\"-y\", \"@modelcontextprotocol\u002Fserver-github\"]\r\n    env:\r\n      # Only this token is passed to the subprocess\r\n      GITHUB_PERSONAL_ACCESS_TOKEN: \"ghp_...\"\r\n```\r\n\r\n### Credential Stripping in Error Messages\r\n\r\nIf an MCP tool call fails, any credential-like patterns in the error message are automatically redacted before being shown to the LLM. This covers:\r\n\r\n- GitHub PATs (`ghp_...`)\r\n- OpenAI-style keys (`sk-...`)\r\n- Bearer tokens\r\n- Generic `token=`, `key=`, `API_KEY=`, `password=`, `secret=` patterns\r\n\r\n## Troubleshooting\r\n\r\n### \"MCP SDK not available -- skipping MCP tool discovery\"\r\n\r\nThe `mcp` Python package is not installed. Install it:\r\n\r\n```bash\r\npip install mcp\r\n```\r\n\r\n### \"No MCP servers configured\"\r\n\r\nNo `mcp_servers` key in `~\u002F.hermes\u002Fconfig.yaml`, or it's empty. Add at least one server.\r\n\r\n### \"Failed to connect to MCP server 'X'\"\r\n\r\nCommon causes:\r\n- **Command not found**: The `command` binary isn't on PATH. Ensure `npx`, `uvx`, or the relevant command is installed.\r\n- **Package not found**: For npx servers, the npm package may not exist or may need `-y` in args to auto-install.\r\n- **Timeout**: The server took too long to start. Increase `connect_timeout`.\r\n- **Port conflict**: For HTTP servers, the URL may be unreachable.\r\n\r\n### \"MCP server 'X' requires HTTP transport but mcp.client.streamable_http is not available\"\r\n\r\nYour `mcp` package version doesn't include HTTP client support. Upgrade:\r\n\r\n```bash\r\npip install --upgrade mcp\r\n```\r\n\r\n### Tools not appearing\r\n\r\n- Check that the server is listed under `mcp_servers` (not `mcp` or `servers`)\r\n- Ensure the YAML indentation is correct\r\n- Look at Hermes Agent startup logs for connection messages\r\n- Tool names are prefixed with `mcp_{server}_{tool}` -- look for that pattern\r\n\r\n### Connection keeps dropping\r\n\r\nThe 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.\r\n\r\n## Examples\r\n\r\n### CodeGraph MCP + VR\u002FWebXR workflow\r\n\r\nWhen adding a source-code graph server such as CodeGraph, use the workflow in `references\u002Fcodegraph-mcp-vr.md`: install\u002Fbuild the CLI, enable a stable `mcp_servers.codegraph` entry, restart Hermes for discovery, verify connected tools, index the target repository, then verify any WebXR\u002FVR viewer via `\u002Fhealthz` and `\u002Fgraph.json` before reporting URLs. Treat dependency audit remediation as a separate change unless the user explicitly asks to fix it.\r\n\r\n### Time Server (uvx)\r\n\r\n```yaml\r\nmcp_servers:\r\n  time:\r\n    command: \"uvx\"\r\n    args: [\"mcp-server-time\"]\r\n```\r\n\r\nRegisters tools like `mcp_time_get_current_time`.\r\n\r\n### Filesystem Server (npx)\r\n\r\n```yaml\r\nmcp_servers:\r\n  filesystem:\r\n    command: \"npx\"\r\n    args: [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\", \"\u002Fhome\u002Fuser\u002Fdocuments\"]\r\n    timeout: 30\r\n```\r\n\r\nRegisters tools like `mcp_filesystem_read_file`, `mcp_filesystem_write_file`, `mcp_filesystem_list_directory`.\r\n\r\n### GitHub Server with Authentication\r\n\r\n```yaml\r\nmcp_servers:\r\n  github:\r\n    command: \"npx\"\r\n    args: [\"-y\", \"@modelcontextprotocol\u002Fserver-github\"]\r\n    env:\r\n      GITHUB_PERSONAL_ACCESS_TOKEN:\"[REDACTED]\"\r\n    timeout: 60\r\n```\r\n\r\nRegisters tools like `mcp_github_list_issues`, `mcp_github_create_pull_request`, etc.\r\n\r\n### Remote HTTP Server\r\n\r\n```yaml\r\nmcp_servers:\r\n  company_api:\r\n    url: \"https:\u002F\u002Fmcp.mycompany.com\u002Fv1\u002Fmcp\"\r\n    headers:\r\n      Authorization: \"Bearer [REDACTED_TOKEN]\"\r\n      X-Team-Id: \"engineering\"\r\n    timeout: 180\r\n    connect_timeout: 30\r\n```\r\n\r\n### Multiple Servers\r\n\r\n```yaml\r\nmcp_servers:\r\n  time:\r\n    command: \"uvx\"\r\n    args: [\"mcp-server-time\"]\r\n\r\n  filesystem:\r\n    command: \"npx\"\r\n    args: [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\", \"\u002Ftmp\"]\r\n\r\n  github:\r\n    command: \"npx\"\r\n    args: [\"-y\", \"@modelcontextprotocol\u002Fserver-github\"]\r\n    env:\r\n      GITHUB_PERSONAL_ACCESS_TOKEN:\"[REDACTED]\"\r\n\r\n  company_api:\r\n    url: \"https:\u002F\u002Fmcp.internal.company.com\u002Fmcp\"\r\n    headers:\r\n      Authorization: \"Bearer [REDACTED_TOKEN]\"\r\n    timeout: 300\r\n```\r\n\r\nAll tools from all servers are registered and available simultaneously. Each server's tools are prefixed with its name to avoid collisions.\r\n\r\n## Sampling (Server-Initiated LLM Requests)\r\n\r\nHermes supports MCP's `sampling\u002FcreateMessage` capability — MCP servers can request LLM completions through the agent during tool execution. This enables agent-in-the-loop workflows (data analysis, content generation, decision-making).\r\n\r\nSampling is **enabled by default**. Configure per server:\r\n\r\n```yaml\r\nmcp_servers:\r\n  my_server:\r\n    command: \"npx\"\r\n    args: [\"-y\", \"my-mcp-server\"]\r\n    sampling:\r\n      enabled: true           # default: true\r\n      model: \"gemini-3-flash\" # model override (optional)\r\n      max_tokens_cap: 4096    # max tokens per request\r\n      timeout: 30             # LLM call timeout (seconds)\r\n      max_rpm: 10             # max requests per minute\r\n      allowed_models: []      # model whitelist (empty = all)\r\n      max_tool_rounds: 5      # tool loop limit (0 = disable)\r\n      log_level: \"info\"       # audit verbosity\r\n```\r\n\r\nServers can also include `tools` in sampling requests for multi-turn tool-augmented workflows. The `max_tool_rounds` config prevents infinite tool loops. Per-server audit metrics (requests, errors, tokens, tool use count) are tracked via `get_mcp_status()`.\r\n\r\nDisable sampling for untrusted servers with `sampling: { enabled: false }`.\r\n\r\n## Notes\r\n\r\n- MCP tools are called synchronously from the agent's perspective but run asynchronously on a dedicated background event loop\r\n- Tool results are returned as JSON with either `{\"result\": \"...\"}` or `{\"error\": \"...\"}`\r\n- The native MCP client is independent of `mcporter` -- you can use both simultaneously\r\n- Server connections are persistent and shared across all conversations in the same agent process\r\n- Adding or removing servers requires restarting the agent (no hot-reload currently)\r\n",{"name":5,"author":42,"license":15,"version":43,"metadata":44,"platforms":49,"description":7},"Hermes Agent","1.0.0",{"hermes":45},{"tags":46,"related_skills":48},[24,33,47],"Integrations",[27],[28,26,29],"main","0d1434f89f4bc6b07e9d272accd8c1013768820f","archive\u002Fskill-md-reviewed\u002Fsha256\u002F14\u002F14d2512c69908a8dafdf1a0a24d327597d0f9e59919169180548129de849554d",0,"https:\u002F\u002Fgithub.com\u002Fzapabob\u002FSkills","https:\u002F\u002Fgithub.com\u002Fzapabob","The Open University of JAPAN　2019-now\r\n\r\nTokyo University of Science　2007-2010","2026-10-26 16:29:01",{"source":8,"skillName":5,"commands":59,"prompt":69,"zipAvailable":70},[60,63,66],{"tool":61,"command":62},"npx","npx skills add zapabob\u002FSkills --skill native-mcp",{"tool":64,"command":65},"bunx","bunx skills add zapabob\u002FSkills --skill native-mcp",{"tool":67,"command":68},"pnpm","pnpm dlx skills add zapabob\u002FSkills --skill native-mcp","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fzapabob\u002FSkills\u002Fblob\u002Fmain\u002Farchive\u002Fskill-md-reviewed\u002Fsha256\u002F14\u002F14d2512c69908a8dafdf1a0a24d327597d0f9e59919169180548129de849554d\u002FSKILL.md",true,[],[73,102,137,164,191,207],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":88,"publishedAt":37},"01M6GJTE1GESGGF9K028Y7753E","xurl","X\u002FTwitter via xurl CLI: post, search, DM, media, v2 API.","https:\u002F\u002Fgithub.com\u002Fzapabob\u002FSkills\u002Fblob\u002Fmain\u002Fregistry\u002Fskills\u002Fxurl\u002Fvariants\u002Fhermes-agent\u002FSKILL.md",[79,82,83],{"categoryNo":80,"categoryName":81,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":84,"categoryName":85,"taxonomyType":86,"taxonomyTypeDesc":87},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[75,89,26,90,91,28,29,92,93,94,95,96,97,35,36,98,50,99,100,101],"openclaw","cli","github","official","search","https","social-media","api","Media","twitter","social","via","post",{"skillNo":103,"name":104,"nameZh":6,"description":105,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":119,"publishedAt":37},"01M6GJT8S1PXQ8WPXT1HSNBWH2","writing-plans","Write implementation plans: bite-sized tasks, paths, code.","https:\u002F\u002Fgithub.com\u002Fzapabob\u002FSkills\u002Fblob\u002Fmain\u002Fregistry\u002Fskills\u002Fwriting-plans\u002Fvariants\u002Fhermes-agent\u002FSKILL.md",[108,111,114,115,116],{"categoryNo":109,"categoryName":110,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":112,"categoryName":113,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":84,"categoryName":85,"taxonomyType":86,"taxonomyTypeDesc":87},{"categoryNo":117,"categoryName":118,"taxonomyType":86,"taxonomyTypeDesc":87},"01JBSEEDCAT000000000000036","内容创作者",[120,121,122,123,26,124,28,125,29,126,127,128,129,130,131,132,133,134,135,136],"writing","writing plans","plans","design","review","workflow","documentation","tasks","development","code","planning","code-review","subagent","write","superpowers","paths","test-driven-development",{"skillNo":138,"name":139,"nameZh":6,"description":140,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":141,"categories":142,"keywords":146,"publishedAt":37},"01M6GJST0H5X7WHBJ3BZK0DVKH","whisper","OpenAI's general-purpose speech recognition model. Supports 99 languages, transcription, translation to English, and language identification. Six model sizes from tiny (39M params) to large (1550M params). Use for speech-to-text, podcast transcription, or multilingual audio processing. Best for robust, multilingual ASR.","https:\u002F\u002Fgithub.com\u002Fzapabob\u002FSkills\u002Fblob\u002Fmain\u002Fregistry\u002Fskills\u002Fwhisper\u002Fvariants\u002Fhermes-agent-optional\u002FSKILL.md",[143],{"categoryNo":144,"categoryName":145,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000016","图像与多媒体",[139,26,28,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163],"openai","speech","multimodal","Transformers","ASR","Audio","text","model","speech recognition","use","general","multilingual","translation","english","identification","processing","Audio Processing",{"skillNo":165,"name":166,"nameZh":6,"description":167,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":168,"categories":169,"keywords":173,"publishedAt":37},"01M6GJSMRQ8EETZTYMG72P70EA","weights-and-biases","W&B: log ML experiments, sweeps, model registry, dashboards.","https:\u002F\u002Fgithub.com\u002Fzapabob\u002FSkills\u002Fblob\u002Fmain\u002Fregistry\u002Fskills\u002Fweights-and-biases\u002Fvariants\u002Fhermes-agent\u002FSKILL.md",[170],{"categoryNo":171,"categoryName":172,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000013","分析与可视化",[174,26,175,176,29,177,178,179,180,181,182,154,183,184,185,186,187,188,189,190],"weights and biases","tensorflow","experiments","pytorch","visualization","registry","real-time","tuning","dashboards","experiment","log","time","Experiment Tracking","Model Registry","Hyperparameter Tuning","WandB","Real-Time Visualization",{"skillNo":192,"name":193,"nameZh":6,"description":194,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":195,"categories":196,"keywords":198,"publishedAt":37},"01M6GJS19KDPRY112JTR326S06","watchers","Poll RSS, JSON APIs, and GitHub with watermark dedup.","https:\u002F\u002Fgithub.com\u002Fzapabob\u002FSkills\u002Fblob\u002Fmain\u002Fregistry\u002Fskills\u002Fwatchers\u002Fvariants\u002Fhermes-agent-optional\u002FSKILL.md",[197],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[193,26,199,91,28,200,30,201,202,203,204,35,36,205,206],"terminal","automation","monitoring","cron","json","rss","devops","with",{"skillNo":208,"name":209,"nameZh":6,"description":210,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":211,"categories":212,"keywords":215,"publishedAt":37},"01M6GJRHJD2A6Q830SWF9W48BC","serving-llms-vllm","vLLM: high-throughput LLM serving, OpenAI API, quantization.","https:\u002F\u002Fgithub.com\u002Fzapabob\u002FSkills\u002Fblob\u002Fmain\u002Fregistry\u002Fskills\u002Fvllm\u002Fvariants\u002Fhermes-agent\u002FSKILL.md",[213,214],{"categoryNo":80,"categoryName":81,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":84,"categoryName":85,"taxonomyType":86,"taxonomyTypeDesc":87},[216,217,218,28,219,147,220,221,222,150,223,96,224,225,226,227,228,229,230,231],"llms","vLLM","serving llms vllm","research","openai api","tensor","Inference Serving","Production","llm serving","High Throughput","PagedAttention","Continuous Batching","Quantization","Tensor Parallelism","high-throughput","throughput"]