docs(mcp): add comprehensive Hermes MCP docs

Expand the MCP feature docs with filtering and capability-aware registration details, add a practical 'Use MCP with Hermes' tutorial, add a config reference page, and wire the new docs into the sidebar and landing page.
2026-03-14 06:36:01 -07:00
parent 04e151714f
commit 67e80def53
6 changed files with 955 additions and 246 deletions
--- a/website/docs/reference/mcp-config-reference.md
+++ b/website/docs/reference/mcp-config-reference.md
@@ -0,0 +1,215 @@
+---
+sidebar_position: 8
+title: "MCP Config Reference"
+description: "Reference for Hermes Agent MCP configuration keys, filtering semantics, and utility-tool policy"
+---
+
+# MCP Config Reference
+
+This page is the compact reference companion to the main MCP docs.
+
+For conceptual guidance, see:
+- [MCP (Model Context Protocol)](/docs/user-guide/features/mcp)
+- [Use MCP with Hermes](/docs/guides/use-mcp-with-hermes)
+
+## Root config shape
+
+```yaml
+mcp_servers:
+  <server_name>:
+    command: "..."      # stdio servers
+    args: []
+    env: {}
+
+    # OR
+    url: "..."          # HTTP servers
+    headers: {}
+
+    enabled: true
+    timeout: 120
+    connect_timeout: 60
+    tools:
+      include: []
+      exclude: []
+      resources: true
+      prompts: true
+```
+
+## Server keys
+
+| Key | Type | Applies to | Meaning |
+|---|---|---|---|
+| `command` | string | stdio | Executable to launch |
+| `args` | list | stdio | Arguments for the subprocess |
+| `env` | mapping | stdio | Environment passed to the subprocess |
+| `url` | string | HTTP | Remote MCP endpoint |
+| `headers` | mapping | HTTP | Headers for remote server requests |
+| `enabled` | bool | both | Skip the server entirely when false |
+| `timeout` | number | both | Tool call timeout |
+| `connect_timeout` | number | both | Initial connection timeout |
+| `tools` | mapping | both | Filtering and utility-tool policy |
+
+## `tools` policy keys
+
+| Key | Type | Meaning |
+|---|---|---|
+| `include` | string or list | Whitelist server-native MCP tools |
+| `exclude` | string or list | Blacklist server-native MCP tools |
+| `resources` | bool-like | Enable/disable `list_resources` + `read_resource` |
+| `prompts` | bool-like | Enable/disable `list_prompts` + `get_prompt` |
+
+## Filtering semantics
+
+### `include`
+
+If `include` is set, only those server-native MCP tools are registered.
+
+```yaml
+tools:
+  include: [create_issue, list_issues]
+```
+
+### `exclude`
+
+If `exclude` is set and `include` is not, every server-native MCP tool except those names is registered.
+
+```yaml
+tools:
+  exclude: [delete_customer]
+```
+
+### Precedence
+
+If both are set, `include` wins.
+
+```yaml
+tools:
+  include: [create_issue]
+  exclude: [create_issue, delete_issue]
+```
+
+Result:
+- `create_issue` is still allowed
+- `delete_issue` is ignored because `include` takes precedence
+
+## Utility-tool policy
+
+Hermes may register these utility wrappers per MCP server:
+
+Resources:
+- `list_resources`
+- `read_resource`
+
+Prompts:
+- `list_prompts`
+- `get_prompt`
+
+### Disable resources
+
+```yaml
+tools:
+  resources: false
+```
+
+### Disable prompts
+
+```yaml
+tools:
+  prompts: false
+```
+
+### Capability-aware registration
+
+Even when `resources: true` or `prompts: true`, Hermes only registers those utility tools if the MCP session actually exposes the corresponding capability.
+
+So this is normal:
+- you enable prompts
+- but no prompt utilities appear
+- because the server does not support prompts
+
+## `enabled: false`
+
+```yaml
+mcp_servers:
+  legacy:
+    url: "https://mcp.legacy.internal"
+    enabled: false
+```
+
+Behavior:
+- no connection attempt
+- no discovery
+- no tool registration
+- config remains in place for later reuse
+
+## Empty result behavior
+
+If filtering removes all server-native tools and no utility tools are registered, Hermes does not create an empty MCP runtime toolset for that server.
+
+## Example configs
+
+### Safe GitHub allowlist
+
+```yaml
+mcp_servers:
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
+    tools:
+      include: [list_issues, create_issue, update_issue, search_code]
+      resources: false
+      prompts: false
+```
+
+### Stripe blacklist
+
+```yaml
+mcp_servers:
+  stripe:
+    url: "https://mcp.stripe.com"
+    headers:
+      Authorization: "Bearer ***"
+    tools:
+      exclude: [delete_customer, refund_payment]
+```
+
+### Resource-only docs server
+
+```yaml
+mcp_servers:
+  docs:
+    url: "https://mcp.docs.example.com"
+    tools:
+      include: []
+      resources: true
+      prompts: false
+```
+
+## Reloading config
+
+After changing MCP config, reload servers with:
+
+```text
+/reload-mcp
+```
+
+## Tool naming
+
+Server-native MCP tools become:
+
+```text
+mcp_<server>_<tool>
+```
+
+Examples:
+- `mcp_github_create_issue`
+- `mcp_filesystem_read_file`
+- `mcp_my_api_query_data`
+
+Utility tools follow the same prefixing pattern:
+- `mcp_<server>_list_resources`
+- `mcp_<server>_read_resource`
+- `mcp_<server>_list_prompts`
+- `mcp_<server>_get_prompt`