mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-25 00:51:20 +00:00
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.
This commit is contained in:
teknium1
parent
04e151714f
commit
67e80def53
6 changed files with 955 additions and 246 deletions
|
|
@ -391,21 +391,28 @@ mcp_servers:
|
|||
|
||||
#### Tools not showing up from MCP server
|
||||
|
||||
**Cause:** Server started but tool discovery failed, or tools are filtered out.
|
||||
**Cause:** Server started but tool discovery failed, tools were filtered out by config, or the server does not support the MCP capability you expected.
|
||||
|
||||
**Solution:**
|
||||
- Check gateway/agent logs for MCP connection errors
|
||||
- Ensure the server responds to the `tools/list` RPC method
|
||||
- Restart the agent — MCP tools are discovered at startup
|
||||
- Review any `tools.include`, `tools.exclude`, `tools.resources`, `tools.prompts`, or `enabled` settings under that server
|
||||
- Remember that resource/prompt utility tools are only registered when the session actually supports those capabilities
|
||||
- Use `/reload-mcp` after changing config
|
||||
|
||||
```bash
|
||||
# Verify MCP servers are configured
|
||||
hermes config show | grep -A 5 mcp_servers
|
||||
hermes config show | grep -A 12 mcp_servers
|
||||
|
||||
# Restart hermes to re-discover tools
|
||||
# Restart Hermes or reload MCP after config changes
|
||||
hermes chat
|
||||
```
|
||||
|
||||
See also:
|
||||
- [MCP (Model Context Protocol)](/docs/user-guide/features/mcp)
|
||||
- [Use MCP with Hermes](/docs/guides/use-mcp-with-hermes)
|
||||
- [MCP Config Reference](/docs/reference/mcp-config-reference)
|
||||
|
||||
#### MCP timeout errors
|
||||
|
||||
**Cause:** The MCP server is taking too long to respond, or it crashed during execution.
|
||||
|
|
|
|||
215
website/docs/reference/mcp-config-reference.md
Normal file
215
website/docs/reference/mcp-config-reference.md
Normal file
|
|
@ -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`
|
||||
Loading…
Add table
Add a link
Reference in a new issue