File size: 4,474 Bytes
9aa5185 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 | ---
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`
|