The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
docs(mcp): tool costs and per-chat spend limits for MCP servers and portable packages
Teknium2fe303419f43
diff --git a/tools/mcp_tool_config.py b/tools/mcp_tool_config.pyindex 912d410bb80..8d42daa6551 100644--- a/tools/mcp_tool_config.py+++ b/tools/mcp_tool_config.py@@ -671,11 +671,14 @@ def _portable_mcp_servers(safe_servers: dict[str, dict]) -> None:portable = get_plugin_manager().get_portable_mcp_servers()for name, cfg in _filter_suspicious_mcp_servers(portable).items():if name in safe_servers:- logger.warning("Portable MCP server '%s' conflicts with native config; skipping", name)native = safe_servers[name]carried = {k: cfg[k] for k in CONFIG_KEYS if k in cfg and k not in native}if carried:safe_servers[name] = {**native, **carried}+ logger.warning("Portable MCP server '%s' conflicts with native config; using the native entry "+ "with the package's declared %s", name, ", ".join(carried))+ else:+ logger.warning("Portable MCP server '%s' conflicts with native config; skipping", name)else:safe_servers[name] = dict(cfg)except Exception:diff --git a/website/docs/developer-guide/plugins/index.md b/website/docs/developer-guide/plugins/index.mdindex 47e5ac56975..d20461a93fd 100644--- a/website/docs/developer-guide/plugins/index.md+++ b/website/docs/developer-guide/plugins/index.md@@ -147,6 +147,42 @@ the package's entry, including its trust. Other harnesses ignore this extension.`trust` can sit beside `app`, `requires` and `liveness` in the same serverentry (see [Application declarations](./application-declarations.md)).+A server whose tools spend money or credits can declare what each call costs+and a budget per chat. Hermes then names the cost in the approval prompt along+with the chat's running total, and a call that would take the chat past+`spend_limit` asks first even when the user has made the server trusted:++```json+{+ "extensions": {+ "com.nousresearch.hermes": {+ "servers": {+ "renders": {+ "trust": "untrusted",+ "costs": {+ "create_image": 20,+ "animate": { "credits": [5, 20], "note": "per animation" }+ },+ "spend_limit": 100,+ "cost_unit": "credits"+ }+ }+ }+ }+}+```++Keys of `costs` are MCP tool names as the server lists them. A cost is a+non-negative number, a `[min, max]` range, or an object with `credits` (number+or range) and a short `note`. `spend_limit` is optional (`0` or absent = no+limit) and `cost_unit` defaults to `credits`. A malformed table makes the+package fail to load with an error naming the key. These map to the native+`tool_costs`, `spend_limit` and `cost_unit` keys (see+[Tool costs and spend limits](../../user-guide/features/mcp.md#tool-costs-and-spend-limits)).+Costs are facts about the server, so they survive a user's same-name+`config.yaml` entry (the way a user widens trust) unless that entry sets the+key itself; the user's `spend_limit` wins, including `0` to turn it off.+A long-running server can also declare a Hermes-specific tool-call `timeout`(in seconds) in `plugin.json`, without changing other servers' defaults:diff --git a/website/docs/reference/mcp-config-reference.md b/website/docs/reference/mcp-config-reference.mdindex 86b311a1a30..0d4aab6f0ed 100644--- a/website/docs/reference/mcp-config-reference.md+++ b/website/docs/reference/mcp-config-reference.md@@ -69,6 +69,9 @@ mcp_servers:| `sampling` | mapping | both | Server-initiated LLM request policy (see MCP guide) || `elicitation` | mapping | both | Server-initiated user-input requests. `enabled` (default `true`) and `timeout` in seconds (default `300`). Form-mode requests route through the approval surface; URL-mode is declined (see MCP guide) || `trust` | string | both | Trust tier: `full` (default) or `untrusted`. On an `untrusted` server, every write-capable tool call (any tool without a `readOnlyHint: true` annotation) requires user approval through the standard approval surface before it runs. `readOnlyHint` is a server-supplied *hint* — a lying server can at most skip approval for tools it claims are read-only, never gain extra access — so mark any server you don't fully control as `untrusted`. The same hint decides whether a call is transparently retried after the transport session expires mid-call: only `readOnlyHint: true` tools are replayed, while unannotated (write-capable) tools return an `outcome_uncertain` error — on a Streamable-HTTP server that expires idle sessions this means the first unannotated call after an idle period may fail and must be verified before re-invoking. Unrecognized values are treated as `untrusted` (fail-closed) A portable package can request `untrusted` for its own server in `plugin.json` (see [Portable Agent Plugins](../developer-guide/plugins/index.md#portable-agent-plugins-v1-packages)); a `config.yaml` entry with the same name always wins |+| `tool_costs` | mapping | both | What each tool spends, keyed by the MCP tool name: a non-negative number, a `[min, max]` range, or `{credits: <number or range>, note: "per animation"}`. The approval prompt names the cost and the chat's running total. Undeclared and zero-cost tools are unaffected. See [Tool costs and spend limits](../user-guide/features/mcp.md#tool-costs-and-spend-limits) |+| `spend_limit` | number | both | Per-chat budget for this server's costed tools (`0`/absent = no limit). A costed call that would take the chat past it asks first, even on a `trust: full` server, and is refused where nobody can answer (cron, `chat -q`) |+| `cost_unit` | string | both | Label shown with costs and totals (default: `credits`) |## Environment variable referencesdiff --git a/website/docs/user-guide/features/mcp.md b/website/docs/user-guide/features/mcp.mdindex c42d98a39e6..ad8a033ac06 100644--- a/website/docs/user-guide/features/mcp.md+++ b/website/docs/user-guide/features/mcp.md@@ -980,6 +980,31 @@ mcp_servers:enabled: false```+## Tool costs and spend limits++Some MCP servers spend real money or credits on every call (image, video and 3D generation, paid APIs). A server entry can declare what each tool costs and a budget per chat:++```yaml+mcp_servers:+ renders:+ command: "render-mcp"+ trust: untrusted+ tool_costs:+ create_image: 20 # about 20 credits per call+ animate: {credits: [5, 20], note: "per animation"} # a range, with a short note+ get_status: 0 # free; same as leaving it out+ spend_limit: 100 # per chat; 0 or absent = no limit+ cost_unit: credits # label in prompts (default: credits)+```++- The approval prompt names the cost: `Costs about 20 credits.` or `Costs 5-20 credits (per animation).`, plus `This chat has used about 40 credits on 'renders' (limit 100).` once the chat has spent something.+- Hermes keeps a running total per chat and per server, counting the declared figure (the top of a range) for every costed call it actually sent. Declined or blocked calls add nothing. The total lives in memory: it is a budget for one conversation, not the vendor's bill.+- With `spend_limit`, a costed call that would take the chat past the limit asks first, even on a `trust: full` server that otherwise never prompts, and every further costed call in that chat asks again ("Allow for this session" does not silence it). Where nobody can answer (cron jobs, `hermes chat -q`, a gateway with no approver), the call is refused without running and the model is told not to retry.+- Below the limit, a `trust: full` server still runs costed tools without asking; on a `trust: untrusted` server every write-capable call already asks and the prompt now carries the cost. Tools annotated `readOnlyHint: true` stay unprompted unless the budget requires it.+- A malformed `tool_costs`, `spend_limit` or `cost_unit` skips the server with an error naming the key, so a budget you declared is never silently dropped.++A [portable plugin package](../../developer-guide/plugins/index.md#portable-agent-plugins-v1-packages) can declare the same table for its server. If you add a same-name `mcp_servers` entry (for example to set `trust: full`), the package's `tool_costs`, `spend_limit` and `cost_unit` still apply unless your entry sets those keys itself; `spend_limit: 0` turns the package's limit off and `tool_costs: {}` drops its costs.+## MCP Elicitation SupportMCP servers can ask the user for structured input mid-tool-call via the `elicitation/create` protocol (mcp Python SDK ≥ 1.11.0). Hermes routes **form-mode** elicitations through its existing approval surface — an interactive prompt in the CLI/TUI, or approval buttons on gateway platforms like Telegram and Slack — so the request reaches you wherever the session lives. **URL-mode** elicitations (where a server points you at an external URL) are declined as unsupported.