Design Least-Privilege MCP Tool Registration

Connecting an MCP server is not the same as approving every capability it advertises. Hermes can filter server-native tools and independently enable resource and prompt utility wrappers. Use those controls to expose the smallest useful surface for the platform and task.

Filtering semantics

A tools.include list is an allowlist. When present, only those original server tool names are registered. An exclude list is a denylist used when no include list is present. If both exist, include wins. This precedence should be documented so a later editor does not assume the denylist cancels an allowed name.

Resources and prompts are separate booleans. Enabling them does not guarantee utility tools appear; Hermes registers them only when the MCP session advertises the corresponding capability. If filters remove every server-native tool and no utilities remain, Hermes does not create an empty runtime toolset.

Least-privilege checklist

Inventory the server’s advertised tools in a non-production environment.
Start with include for production workflows.
Separate read, write, delete, refund, admin, and credential operations.
Disable resources when the workflow does not need arbitrary resource reads.
Disable prompts when server-provided prompt templates are unnecessary.
Use original MCP names in filters, before Hermes sanitizes them for tool registration.
Record the generated mcp-<server> toolset and intended platforms.
Reload configuration and read back the actual registered tool list.
Test that one allowed and one forbidden operation behave as designed.
Re-review after every server upgrade because advertised capabilities can change.

Names and dynamic toolsets

Registered tools are prefixed with the server name, and hyphens or dots are converted to underscores for function-calling compatibility. Filters still use the server’s original names. Each configured MCP server can also create a dynamic mcp-<server> toolset, which can be referenced in session or platform configuration.

Do not rely on a broad all setting as an authorization model. Capability prerequisites, platform rules, plugins, and deliberately opt-in toolsets can still change what appears. The effective tool list—not the intended YAML—is the release record.

Common pitfalls

Using only an exclude list for a high-risk server with a rapidly changing tool catalog.
Writing sanitized names in include and wondering why nothing registers.
Enabling resource reads on a server connected to private repositories or documents without need.
Assuming prompt utilities are harmless because they do not look like mutations.
Treating a missing tool as a network failure when capability-aware registration intentionally omitted it.
Enabling a dynamic MCP toolset on every messaging platform.
Forgetting to repeat the inventory after a server upgrade.

Verification steps

Capture the server’s advertised native tools, resources, and prompts in a safe environment.
Apply the production allowlist and reload MCP configuration.
Read back the effective registered names and compare them with the approval record.
Call one allowed read-only tool successfully.
Confirm a forbidden destructive tool is absent rather than merely documented as disallowed.
Disable all native tools while leaving one supported utility class enabled and verify the expected resource-only or prompt-only shape.
Remove all capabilities and confirm Hermes does not create an empty runtime toolset.

Official documentation

https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference