Skip to main content
Glama
Hermes Toolkit MCP

Hermes Toolkit MCP

by hermegeddon

Hermes Toolkit MCP

Hermes Toolkit MCP is a safety-first MCP operations cockpit for Hermes Agent installations. It exposes typed, evidence-producing management primitives rather than a generic proxy for every Hermes tool or an untyped “ask Hermes” bridge.

Experimental: the no-config default exposes the owner-tier surface for local development. Review the policy model and configure policy.mode: read_only or narrower feature gates before connecting it to an installation you care about.

The project is maintained on a best-effort basis. See CONTRIBUTING.md for development guidance and SECURITY.md for private vulnerability reporting.

Framework decision

The package uses the official Python mcp SDK as the protocol baseline (mcp>=1.9,<2). The stdio server keeps stdout reserved for MCP protocol frames; diagnostics belong on stderr or in bounded artifacts. FastMCP is intentionally not used in this vertical slice because the plan calls for explicit control over policy gates, result envelopes, artifact receipts, and stdout/stderr behavior.

Related MCP server: CodexPro Runtime

Implemented MCP tools

Tier

Tools

M1 read-only

hermes_status_overview, hermes_detect_install, hermes_toolkit_info, hermes_profiles_list, hermes_config_summary

M2a API docs

hermes_api_docs_list, hermes_api_docs_read, hermes_kanban_api_docs_list, hermes_kanban_api_docs_read

M2c Hermes API metadata

hermes_api_models_list, hermes_api_capabilities_get, hermes_api_health, hermes_api_health_detailed, hermes_api_skills_list, hermes_api_toolsets_list

M2c Hermes API calls

hermes_api_chat_completions, hermes_api_responses_create, hermes_api_responses_get, hermes_api_responses_delete, hermes_api_runs_start, hermes_api_runs_get, hermes_api_runs_events, hermes_api_runs_stop, hermes_api_runs_approval, hermes_api_jobs_list, hermes_api_jobs_create, hermes_api_jobs_get, hermes_api_jobs_update, hermes_api_jobs_delete, hermes_api_jobs_pause, hermes_api_jobs_resume, hermes_api_jobs_run

M2c Kanban API metadata

hermes_kanban_board_get, hermes_kanban_task_get, hermes_kanban_workers_active, hermes_kanban_run_get, hermes_kanban_run_inspect, hermes_kanban_profiles_list, hermes_kanban_orchestration_get, hermes_kanban_config_get

M2c Kanban API calls

hermes_kanban_task_create, hermes_kanban_task_update, hermes_kanban_tasks_bulk_update, hermes_kanban_task_comment_create, hermes_kanban_link_create, hermes_kanban_link_delete, hermes_kanban_task_specify, hermes_kanban_task_decompose, hermes_kanban_profile_update, hermes_kanban_orchestration_update, hermes_kanban_dispatch_nudge

M2d smoke / M3 eval / M4-M5 diagnostics

hermes_api_smoke, hermes_eval_suites_list, hermes_eval_run, hermes_eval_start, hermes_job_status, hermes_job_cancel, hermes_deploy_guard_check, hermes_config_compare_surfaces, hermes_deploy_repair_plan, hermes_gateway_status, hermes_log_tail

M6 skill workflow

hermes_skills_list, hermes_skill_read, hermes_skill_eval_start, hermes_skill_patch_proposal

M7 fallback

hermes_agent_ask_fallback

M8 mutation

hermes_skill_patch_apply, hermes_config_patch_apply, hermes_gateway_restart, hermes_deploy_repair_apply

Goals

  • Provide a curated MCP server for Hermes management and diagnostics.

  • Treat this package as experimental local tooling: the no-config default exposes all implemented feature tiers, while operators can set policy.mode: read_only or lower gates explicitly for conservative deployments.

  • Model policy tiers, tool metadata, redaction, path containment, API route-table controls, and artifact receipts before live calls.

  • Produce structured evidence and private artifacts for non-trivial operations.

  • Prefer typed wrappers and documented route tables over generic fallback tools.

  • Keep hermes_agent_ask_fallback visibly last resort: it is optional, gated by api_call policy plus live/model/tool/external-side-effect gates, and should never be the primary workflow.

Non-goals and default denials for M1/M2a/M2b/M2c/M2d/M3/M4/M5/M6/M7/M8

  • No user-facing raw Hermes API fallback MCP tool is provided; M2b only adds the reusable internal client/route-table substrate and M2c exposes the first typed API wrapper.

  • No global nullable-schema rewrite or compatibility normalizer is implemented; the consuming client's schema-adapter defect remains a vendor/external-lane issue unless explicitly fixed in an editable client repository and accepted by review.

  • No network refresh is performed during normal API docs tool or resource calls; M2a uses a bundled snapshot of the official API server docs.

  • No non-loopback chat-completions smoke is enabled by policy alone; M2c targets mocked/local loopback endpoints unless the operator separately enables the non-local opt-in env var.

  • No live eval run happens merely because tools are visible; M3 permits dry/structural suites without model calls and requires live_eval=true plus HERMES_TOOLKIT_MCP_ALLOW_LIVE_EVAL=1 for non-dry suites.

  • No deploy repair is applied by the M4/M5 guard tools: they do not fetch, switch branches, merge, restart services, write config, or mutate live checkouts.

  • No skill write is applied by the M6 skill workflow tools: reads are bounded, eval start only writes eval artifacts, and patch proposals write proposal artifacts only.

  • The MCP server does not implicitly migrate launchers or credential sources, publish packages, push repositories, or post public issues; those remain explicit operator actions outside its typed tool calls.

  • M8 mutation tools are visible in the experimental default surface, but each apply path still requires exact-scope hashes, a confirmation nonce, private backups/receipts, and configured command hashes for owner actions.

  • No package publication, git push/merge/rewrite, third-party tracker write, or unconfigured service mutation is performed implicitly.

  • No generic “all Hermes tools” proxy is provided.

  • No hermes_api_request_fallback tool is exposed; route-table raw fallback remains denied until every route has explicit risk classification and denial tests.

  • No unrestricted shell/file bridge is exposed.

  • No secrets or raw environment values are printed.

Package layout

M1 contains bootstrap/safety primitives plus the first read-only MCP discovery tools:

  • config.py — typed YAML/env-loaded configuration model.

  • policy.py — canonical policy lattice and per-tool metadata decisions.

  • redaction.py — central redaction primitives.

  • paths.py — path containment and symlink escape checks.

  • artifacts.py — private artifact writer and manifest schema.

  • api_client.py — M2b fail-closed Hermes API route table, typed-wrapper authorization, httpx client, and redacted request/result/response receipts.

  • chat_completions.py — M2c typed hermes_api_chat_completions request validation and mocked/local API wrapper.

  • evals.py — M3 eval-suite listing, dry/live gate enforcement, synchronous/asynchronous eval jobs, and request/result/summary/stdout/stderr/report artifacts.

  • diagnostics.py — M4/M5 read-only deploy guard, config comparison, gateway status/log tail diagnostics, proposal-only repair plans, and gated API smoke.

  • skills.py — M6 skill list/read/eval-start wrappers, linked-file containment, and proposal-only skill patch artifacts.

  • mutations.py — M8 gated mutation apply tools for exact-scope skill/config patches, configured gateway restarts, and configured deploy repair commands.

  • discovery.py — read-only Hermes/toolkit/profile/config discovery helpers.

  • api_docs.py and snapshots/hermes-api-server.md — bundled official API server docs index, resources, source provenance, and planned wrapper mapping.

  • server.py — official SDK stdio MCP server with registration-time and call-time policy enforcement.

  • docs/tool-contracts.md — MCP tool/resource contracts and safety metadata.

Quick start

uv run hermes-toolkit-mcp --help
uv run hermes-toolkit-mcp --config examples/read-only.yaml config-check --json
npx --yes mcporter list --stdio "uv run hermes-toolkit-mcp" --schema --json
npx --yes mcporter call --stdio "uv run hermes-toolkit-mcp" --output json hermes_detect_install
uv run pytest

Running uv run hermes-toolkit-mcp with no subcommand starts the stdio MCP server. Use --help or config-check for terminal-friendly output.

M1 read-only tools

  • hermes_status_overview

  • hermes_detect_install

  • hermes_toolkit_info (reports degraded verdict/warnings when eval paths are denied or missing)

  • hermes_profiles_list

  • hermes_config_summary

All five tools register with read-only/idempotent MCP annotations, min_tier=read_only, no live-call/model-spend/agent-tool/external-side-effect flags, and no mutation/destructive flags. The same policy metadata is checked at registration time and call time.

M2a API docs resources and tools

M2a adds the documentation half of the Hermes API track without making live API, model, tool, or network calls during normal MCP operations:

  • hermes_api_docs_list — lists bundled hermes-docs://api-server/* resources, section slugs, snapshot provenance, and planned API wrapper mapping.

  • hermes_api_docs_read — reads one bundled section by slug or resource URI; defaults to the full snapshot.

  • MCP resources under hermes-docs://api-server/*, including full, overview, endpoint sections such as post-v1-chat-completions, and operational sections such as authentication and configuration.

The snapshot is curated from the official source URL https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server, records snapshot timestamp/version metadata, and replaces example credential-looking values with placeholders. These docs surfaces register at min_tier=api_docs, remain read-only/idempotent, and are intentionally separate from future prompt-bearing API wrappers.

M2b API route table and client substrate

M2b adds the internal client substrate required before any raw-ish Hermes API fallback can exist. It does not expose a generic API proxy MCP tool. The reusable HermesApiClient wraps httpx behind a fail-closed route table that records method, path pattern, risk flags, minimum policy tier, typed wrapper name, per-route body limits, allowed caller-supplied headers, and fallback permission.

Calls are allowed only when the route is known, the configured policy tier is sufficient, allow_live_api_calls is enabled, and the caller names the matching typed wrapper. Unknown /v1/* routes, explicit unsafe/unwrapped endpoints such as /api/sessions/{id}/chat, raw fallback attempts, arbitrary headers, redirects, non-JSON responses, and oversized bodies fail closed with stable safe error codes.

When a configured API-key environment variable is present, the client adds bearer auth to the outbound request but receipts record only the env-var name and presence boolean. Request/result/response receipt artifacts include hashes, byte counts, bounded redacted previews, route metadata, status/content-type metadata, and never the raw bearer value.

M2c typed Hermes API wrappers

M2c exposes the first prompt-bearing typed API wrapper (hermes_api_chat_completions) plus read-only metadata wrappers for the Hermes API server surface. All API wrappers route through the fail-closed HermesApiClient and write redacted request/result/response receipts.

  • hermes_api_chat_completions — OpenAI-compatible POST /v1/chat/completions with bounded messages, stream=false, and mocked/local-first non-loopback opt-in.

  • hermes_api_responses_create / hermes_api_responses_get / hermes_api_responses_delete — typed OpenAI Responses API wrappers.

  • hermes_api_runs_start / hermes_api_runs_get / hermes_api_runs_events / hermes_api_runs_stop / hermes_api_runs_approval — typed Runs API wrappers.

  • hermes_api_jobs_list / hermes_api_jobs_create / hermes_api_jobs_get / hermes_api_jobs_update / hermes_api_jobs_delete / hermes_api_jobs_pause / hermes_api_jobs_resume / hermes_api_jobs_run — typed scheduler/cron job wrappers. hermes_api_jobs_list uses concrete limit=25/offset=0 defaults, omits prompt bodies from summaries (use hermes_api_jobs_get for the full definition), records upstream body bytes/hash in receipts, and returns pagination fields plus a 24 KiB item budget/32 KiB final-envelope budget.

  • hermes_api_skills_list — GET /v1/skills returning structured skill metadata with optional category/limit/offset filters.

  • hermes_api_toolsets_list — GET /v1/toolsets returning structured toolset metadata with optional category/limit/offset filters.

  • hermes_api_models_list, hermes_api_capabilities_get, hermes_api_health, hermes_api_health_detailed — read-only server metadata.

State-changing wrappers register at min_tier=api_call and require the live, model-spend (where applicable), agent-tool, and external-side-effect gates. Read-only metadata wrappers register at min_tier=api_metadata and require live and external-side-effect gates. The experimental no-config default enables those gates; conservative deployments can lower policy.mode or individual gates.

hermes_api_skills_list and hermes_api_toolsets_list are typed GET wrappers. They accept optional category, limit, and offset parameters and are listed in the bundled API docs skills-and-toolsets-discovery section as implemented_typed_wrapper.

M2d protocol smoke, denials, and fallback guardrails

M2d completes the protocol/safety validation layer around the M2 API surfaces:

  • mcporter list --stdio "uv run hermes-toolkit-mcp" --schema --json is the protocol smoke for tool/resource discovery; stdout remains reserved for MCP/JSON protocol output while diagnostics stay off stdout.

  • The expected API-wrapper sequence reads the bundled docs resource first, for example hermes-docs://api-server/post-v1-chat-completions, then invokes the typed hermes_api_chat_completions wrapper against a mocked/local endpoint.

  • hermes_api_chat_completions returns top-level run_id and artifact_dir values plus absolute request/result/response receipt artifact paths.

  • A generic raw hermes_api_request_fallback MCP tool remains absent. Internally classified routes still set allow_fallback=false, and raw fallback authorization attempts are denied with RAW_FALLBACK_DENIED.

  • hermes_agent_ask_fallback remains visibly last resort. run and start now require why_no_typed_tool_fits, docs_resource_consulted, typed_wrapper_checked, risk_acknowledgement, and expected_evidence; the bridge reads the named docs resource and writes docs-consulted.json before any backend/API wrapper call.

M3 eval harness integration

M3 wraps the configured Hermes eval harness behind the eval policy tier:

  • hermes_eval_suites_list lists suite files from toolkit.suites_dir, including dry/structural markers and case counts, without executing the harness. Discovery and execution use the same post-symlink configured-path resolver; an external target not in policy.allowed_paths is reported as PATH_DENIED with a degraded verdict.

  • hermes_eval_run executes one bounded suite synchronously and writes private request.json, result.json, summary.json, stdout.txt, stderr.txt, report.md, and manifest.json artifacts.

  • hermes_eval_start starts the same run path as an in-process async job; hermes_job_status polls it and hermes_job_cancel requests best-effort cancellation.

  • Dry/structural suites must declare a top-level or metadata mcp_dry_run, dry_run, structural, or mode: dry marker. Non-dry suites require live_eval=true, all live/model/tool/external policy gates, and HERMES_TOOLKIT_MCP_ALLOW_LIVE_EVAL=1.

M4/M5 deploy guard and gateway/API diagnostics

M4/M5 adds deploy-readiness and runtime-diagnostic surfaces without granting deploy authority:

  • hermes_deploy_guard_check is read-only and probes an allowlisted live git worktree for branch, HEAD, cleanliness, and symlink/path-containment failures. It never fetches, switches branches, merges, restarts, or writes config.

  • hermes_config_compare_surfaces compares selected top-level YAML config keys across two allowlisted config files. Secret-like keys are reported by presence only, and output is redacted.

  • hermes_deploy_repair_plan is available only at propose_mutation; it writes private repair-plan.json and repair-plan.md artifacts and explicitly performs no git/service/config mutation.

  • hermes_gateway_status reads configured pid/lock/log-path state and process presence when a pid file is configured; it never starts, stops, restarts, or signals a process. It parses plain-decimal and Hermes 0.18.2 JSON PID files; malformed, stale, unreadable, missing, or denied states surface degraded or blocked with a warning rather than a silent pass.

  • hermes_log_tail tails only configured hermes.gateway.allowed_log_paths, with bounded reads and redaction; arbitrary log paths are denied. An empty allowlist is a valid fail-closed configuration.

  • hermes_api_smoke is gated at api_call with all live/model/tool/external gates. It separates endpoint reachability, auth acceptance, model invocation, and assistant-answer evidence, writes smoke-summary.json, and requires HERMES_TOOLKIT_MCP_ALLOW_LIVE_API_SMOKE=1 for non-loopback API bases.

M6 skill workflow support

M6 adds proposal-first skill workflow tools; direct skill mutation is separated into M8 exact-scope apply tools:

  • hermes_skills_list lists toolkit/home/profile skill directories, frontmatter summaries, and linked files under references/, templates/, scripts/, or assets/. Bare calls default to limit=25, compact summaries, and total_count/returned_count/next_offset pagination fields; projected items stay within a 24 KiB byte budget and the final envelope stays within a 32 KiB target. Use detail="full" for the rich shape, still subject to the same bounds.

  • hermes_skill_read reads a bounded SKILL.md or linked file after resolving the skill and linked file under allowed roots and the skill directory.

  • hermes_skill_eval_start validates a skill id before starting the existing dry/live-gated eval job path, writing eval artifacts but not skill files.

  • hermes_skill_patch_proposal is available only at propose_mutation; it writes private proposal.json, proposal.patch, and manifest artifacts while recording proposal_only=true and no_skill_write/no_git_operation non-actions.

Actual skill writes are performed only by M8 apply tools, which require exact-scope hashes, a matching confirmation nonce, and path-containment checks.

M7 optional fallback bridge

M7 adds hermes_agent_ask_fallback as a last-resort, artifact-producing bridge. It is visible in the experimental default surface, but run and start requests must explain why no typed tool fits, name the bundled docs resource consulted, name the typed wrapper checked, acknowledge risk, and list expected evidence.

M8 gated mutation tools

M8 adds mutation-capable tools. They are visible in the experimental default surface, but execution remains fail-closed unless each exact-scope gate passes:

  • hermes_skill_patch_apply applies an exact-scope skill-file patch only with expected_original_sha256 and a confirmation nonce from policy.mutation_confirmation_nonce_env.

  • hermes_config_patch_apply applies an exact-scope config-file patch only with matching file SHA-256, parse validation for YAML/JSON/TOML, and a confirmation nonce.

  • hermes_gateway_restart is owner-tier/destructive and runs only a preconfigured hermes.mutation_commands.gateway_restart argv list after command-hash and nonce gates pass.

  • hermes_deploy_repair_apply is owner-tier/destructive and runs only a preconfigured hermes.mutation_commands.deploy_repair argv list against a verified repair-plan.json artifact after command-hash, plan-hash, and nonce gates pass.

Every apply path writes a private artifact receipt. File patch tools write private target-adjacent backups and a redacted patch; command tools capture redacted stdout/stderr and never use a shell string.

Fixture contract

Tests use static fake fixtures under tests/fixtures/ and temporary directories from tmp_path. They must not depend on a developer's live home directory, Hermes installation, toolkit checkout, external tracker state, or API server.

License

Hermes Toolkit MCP is licensed under the MIT License.

Available Tools

73 tools
hermes_agent_ask_fallbackAsk Hermes fallback (last resort)A

Last-resort prompt bridge to a configured Hermes Agent backend after typed tools do not fit. Requires why_no_typed_tool_fits, docs_resource_consulted, typed_wrapper_checked, risk_acknowledgement, and expected_evidence, writes private artifacts, supports async jobs, and warns when a typed tool would be better.

Inputs: home, job_id, prompt, backend, +10 more. Returns: Standard MCP tool result envelope for future tools.

hermes_api_capabilities_getGet Hermes API capabilitiesA
Read-onlyIdempotent

Typed GET /v1/capabilities wrapper that returns the configured Hermes API server capability surface, writing redacted receipts.

Inputs: capability. Returns: Standard MCP tool result envelope for future tools.

hermes_api_chat_completionsCreate Hermes API chat completionA

Typed OpenAI-compatible POST /v1/chat/completions wrapper for mocked/local Hermes API endpoints. Requires api_call policy plus live/model/tool/external-side-effect gates, disables streaming in v0, and writes redacted request/result/response receipts.

Inputs: messages (required), model, stream, max_tokens, +1 more. Returns: Standard MCP tool result envelope for future tools.

hermes_api_docs_listList Hermes API docs snapshot sectionsA
Read-onlyIdempotent

List bundled Hermes API server documentation resources, section slugs, snapshot provenance, and planned wrapper mapping without network refresh.

Inputs: no named parameters. Returns: Standard MCP tool result envelope for future tools.

hermes_api_docs_readRead Hermes API docs snapshot sectionA
Read-onlyIdempotent

Read one bundled Hermes API server docs section by slug or hermes-docs://api-server/* resource URI without network, API, model, or tool calls.

Inputs: uri, section. Returns: Standard MCP tool result envelope for future tools.

hermes_api_healthCheck Hermes API healthB
Read-onlyIdempotent

Typed GET /health wrapper that checks the configured Hermes API server liveness, writing redacted receipts.

Inputs: check_connectivity. Returns: Standard MCP tool result envelope for future tools.

hermes_api_health_detailedCheck Hermes API detailed healthA
Read-onlyIdempotent

Typed GET /health/detailed wrapper that checks the configured Hermes API server detailed health, writing redacted receipts.

Inputs: include. Returns: Standard MCP tool result envelope for future tools.

hermes_api_jobs_createCreate Hermes scheduled jobB

Typed POST /api/jobs wrapper that creates a scheduled Hermes cron job with prompt, schedule, skills, provider/model overrides, and delivery target, writing redacted receipts.

Inputs: prompt (required), schedule (required), model, skills, +2 more. Returns: Standard MCP tool result envelope for future tools.

hermes_api_jobs_deleteDelete Hermes scheduled jobA

Typed DELETE /api/jobs/{job_id} wrapper that removes a scheduled Hermes cron job and cancels any in-flight run, writing redacted receipts.

Inputs: job_id (required). Returns: Standard MCP tool result envelope for future tools.

hermes_api_jobs_getGet Hermes scheduled jobA
Read-onlyIdempotent

Typed GET /api/jobs/{job_id} wrapper that fetches one scheduled Hermes cron job's definition and last-run state, writing redacted receipts.

Inputs: job_id (required). Returns: Standard MCP tool result envelope for future tools.

hermes_api_jobs_listList Hermes scheduled jobsB
Read-onlyIdempotent

Typed GET /api/jobs wrapper that lists scheduled Hermes cron jobs from the configured Hermes API server, with optional limit, offset, and status filter, writing redacted receipts.

Inputs: limit, offset, status. Returns: Standard MCP tool result envelope for future tools.

hermes_api_jobs_pausePause Hermes scheduled jobB

Typed POST /api/jobs/{job_id}/pause wrapper that suspends a scheduled Hermes cron job without deleting it, writing redacted receipts.

Inputs: job_id (required). Returns: Standard MCP tool result envelope for future tools.

hermes_api_jobs_resumeResume Hermes scheduled jobA

Typed POST /api/jobs/{job_id}/resume wrapper that resumes a previously paused scheduled Hermes cron job, writing redacted receipts.

Inputs: job_id (required). Returns: Standard MCP tool result envelope for future tools.

hermes_api_jobs_runRun Hermes scheduled job nowB

Typed POST /api/jobs/{job_id}/run wrapper that triggers a scheduled Hermes cron job to run immediately, out of schedule, writing redacted receipts.

Inputs: job_id (required). Returns: Standard MCP tool result envelope for future tools.

hermes_api_jobs_updateUpdate Hermes scheduled jobA

Typed PATCH /api/jobs/{job_id} wrapper that partially updates a scheduled Hermes cron job (prompt, schedule, skills, provider/model, delivery, enabled), writing redacted receipts.

Inputs: job_id (required), model, prompt, skills, +4 more. Returns: Standard MCP tool result envelope for future tools.

hermes_api_models_listList Hermes API modelsA
Read-onlyIdempotent

Typed GET /v1/models wrapper that lists available models from the configured Hermes API server, writing redacted request/result/response receipts.

Inputs: include_internal. Returns: Standard MCP tool result envelope for future tools.

hermes_api_responses_createCreate Hermes API responseA

Typed OpenAI Responses API POST /v1/responses wrapper. Requires api_call policy plus live/model/tool/external-side-effect gates, disables streaming in v0, supports previous_response_id / conversation chaining, and writes redacted request/result/response receipts.

Inputs: input (required), model, store, stream, +4 more. Returns: Standard MCP tool result envelope for future tools.

hermes_api_responses_deleteDelete Hermes API responseA

Typed DELETE /v1/responses/{id} wrapper that deletes a stored response from the configured Hermes API server, writing redacted receipts.

Inputs: response_id (required). Returns: Standard MCP tool result envelope for future tools.

hermes_api_responses_getGet Hermes API responseA
Read-onlyIdempotent

Typed GET /v1/responses/{id} wrapper that retrieves a stored response from the configured Hermes API server, writing redacted receipts.

Inputs: response_id (required). Returns: Standard MCP tool result envelope for future tools.

hermes_api_runs_approvalApprove or deny Hermes runA

Typed POST /v1/runs/{run_id}/approval wrapper that submits an approval decision for a paused Hermes run, writing redacted receipts. Requires api_call tier with live, agent-tool, and external-side-effect gates.

Inputs: run_id (required), approved (required), note, scope. Returns: Standard MCP tool result envelope for future tools.

hermes_api_runs_eventsGet Hermes run eventsA

Typed GET /v1/runs/{run_id}/events wrapper that returns non-streaming event metadata for a Hermes run, writing redacted receipts. This is not a streaming SSE/WebSocket proxy.

Inputs: run_id (required), after, limit, include. Returns: Standard MCP tool result envelope for future tools.

hermes_api_runs_getGet Hermes runB

Typed GET /v1/runs/{run_id} wrapper that reads a Hermes run status, writing redacted receipts. Requires api_call tier with live and external-side-effect gates.

Inputs: run_id (required). Returns: Standard MCP tool result envelope for future tools.

hermes_api_runs_startStart Hermes runA

Typed POST /v1/runs wrapper that starts a Hermes agent run from a prompt, writing redacted request/result/response receipts. Requires api_call tier with live, model, agent-tool, and external-side-effect gates.

Inputs: prompt (required), home, tags, model, +3 more. Returns: Standard MCP tool result envelope for future tools.

hermes_api_runs_stopStop Hermes runA

Typed POST /v1/runs/{run_id}/stop wrapper that requests a Hermes run stop, writing redacted receipts. Requires api_call tier with live, agent-tool, and external-side-effect gates.

Inputs: run_id (required), reason, wait_seconds. Returns: Standard MCP tool result envelope for future tools.

hermes_api_skills_listList Hermes API skillsA
Read-onlyIdempotent

Typed GET /v1/skills wrapper that lists available skills from the configured Hermes API server, writing redacted receipts.

Inputs: limit, offset, category. Returns: Standard MCP tool result envelope for future tools.

hermes_api_smokeSmoke-test Hermes API serverC

Gated Hermes API smoke that separates endpoint reachability, auth acceptance, model invocation, and assistant answer evidence, writing redacted artifacts.

Inputs: home, model, prompt, profile, +2 more. Returns: Standard MCP tool result envelope for future tools.

hermes_api_toolsets_listList Hermes API toolsetsA
Read-onlyIdempotent

Typed GET /v1/toolsets wrapper that lists available toolsets from the configured Hermes API server, writing redacted receipts.

Inputs: limit, offset, category. Returns: Standard MCP tool result envelope for future tools.

hermes_config_compare_surfacesCompare Hermes config surfacesB
Read-onlyIdempotent

Compare selected top-level config keys across two allowlisted YAML surfaces with redaction and presence-only handling for sensitive values.

Inputs: left_config (required), right_config (required), home, keys, +4 more. Returns: Standard MCP tool result envelope for future tools.

hermes_config_patch_applyApply gated Hermes config patchC

Apply an exact-scope config-file patch only when mutation policy, allow_config_write, expected sha256, parse validation, and confirmation nonce gates all pass; writes a private backup and receipt artifact.

Inputs: reason (required), new_string (required), old_string (required), config_path (required), +6 more. Returns: Standard MCP tool result envelope for future tools.

hermes_config_summaryHermes config summaryA
Read-onlyIdempotent

Read Hermes config shape and MCP server transport metadata while redacting secret values and reporting env presence only.

Inputs: home, profile, toolkit_root. Returns: Standard MCP tool result envelope for future tools.

hermes_deploy_guard_checkCheck Hermes deploy guardA
Read-onlyIdempotent

Read-only git/live-checkout guard that verifies branch, HEAD, cleanliness, and path containment without fetch, checkout, restart, or config writes.

Inputs: live_checkout (required), home, profile, toolkit_root, +5 more. Returns: Standard MCP tool result envelope for future tools.

hermes_deploy_repair_applyApply gated Hermes deploy repair commandB
Destructive

Run a preconfigured deploy repair command against a verified repair-plan artifact only at owner policy tier with git/config/gateway/external gates, command-hash, plan-hash, and confirmation nonce gates.

Inputs: reason (required), confirmation_nonce (required), proposal_artifact_dir (required), expected_repair_plan_sha256 (required… Returns: Standard MCP tool result envelope for future tools.

hermes_deploy_repair_planWrite Hermes deploy repair proposalA

Write a proposal-only deploy repair artifact based on deploy guard evidence; performs no git, service, or config mutation.

Inputs: live_checkout (required), home, profile, toolkit_root, +5 more. Returns: Standard MCP tool result envelope for future tools.

hermes_detect_installDetect Hermes installationA
Read-onlyIdempotent

Detect local Hermes CLI/home/profile/config/toolkit surfaces without mutation or live API/model calls.

Inputs: home, profile, toolkit_root. Returns: Standard MCP tool result envelope for future tools.

hermes_eval_runRun Hermes eval suiteA

Run one bounded Hermes eval suite synchronously through the configured eval harness. Dry/structural suites run without live-model opt-in; non-dry/live eval requires live_eval=true, HERMES_TOOLKIT_MCP_ALLOW_LIVE_EVAL=1, and the live/model/tool/external policy gates. Writes request/result/summary/stdout/stderr/report artifacts.

Inputs: suite (required), home, model, backend, +8 more. Returns: Standard MCP tool result envelope for future tools.

hermes_eval_startStart Hermes eval suite jobA

Start one bounded Hermes eval suite as an in-process async job with the same dry/live gates as hermes_eval_run. Poll with hermes_job_status and cancel with hermes_job_cancel.

Inputs: suite (required), home, model, backend, +8 more. Returns: Standard MCP tool result envelope for future tools.

hermes_eval_suites_listList Hermes eval suitesA
Read-onlyIdempotent

List configured Hermes eval suite files, dry-run markers, case counts, and harness path state without executing the harness.

Inputs: home, profile, toolkit_root. Returns: Standard MCP tool result envelope for future tools.

hermes_gateway_restartRestart Hermes gateway through configured commandA
Destructive

Run a preconfigured gateway restart command only at owner policy tier with external-side-effect, allow_gateway_restart, command-hash, and confirmation nonce gates; captures redacted stdout/stderr artifacts.

Inputs: reason (required), confirmation_nonce (required), expected_restart_command_sha256 (required), home, +3 more. Returns: Standard MCP tool result envelope for future tools.

hermes_gateway_statusInspect Hermes gateway statusA
Read-onlyIdempotent

Inspect configured gateway pid/lock/log path state without starting, stopping, restarting, or mutating services.

Inputs: home, profile, toolkit_root. Returns: Standard MCP tool result envelope for future tools.

hermes_job_cancelCancel Hermes Toolkit jobC

Best-effort cancel of a process-local Hermes Toolkit MCP async eval job by job_id/run_id.

Inputs: job_id (required), home, profile, toolkit_root. Returns: Standard MCP tool result envelope for future tools.

hermes_job_statusCheck Hermes Toolkit job statusA
Read-onlyIdempotent

Poll a process-local Hermes Toolkit MCP async eval job by job_id/run_id and return current artifact/result status.

Inputs: job_id (required), home, profile, toolkit_root. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_api_docs_listList Hermes Kanban API docs snapshot sectionsA
Read-onlyIdempotent

List bundled Hermes Kanban REST API documentation resources, section slugs, snapshot provenance, and planned wrapper mapping without network refresh.

Inputs: no named parameters. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_api_docs_readRead Hermes Kanban API docs snapshot sectionA
Read-onlyIdempotent

Read one bundled Hermes Kanban API docs section by slug or hermes-docs://kanban-api/* resource URI without network, API, model, or tool calls.

Inputs: uri, section. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_assignees_listList Kanban assigneesA
Read-onlyIdempotent

Typed GET /api/plugins/kanban/assignees wrapper that lists available assignee profiles with optional board-scoped task counts, writing redacted receipts.

Inputs: board. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_board_getGet Kanban boardA
Read-onlyIdempotent

Typed GET /api/plugins/kanban/board wrapper that reads a Kanban board with optional board slug, tenant, archived filter, limit, and offset, writing redacted receipts.

Inputs: board, limit, offset, tenant, +1 more. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_boards_listList Kanban boardsA
Read-onlyIdempotent

Typed GET /api/plugins/kanban/boards wrapper that lists every board on disk with metadata, task counts, health, and the active board slug, writing redacted receipts.

Inputs: include_counts, include_archived. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_config_getGet Kanban dashboard configA
Read-onlyIdempotent

Typed GET /api/plugins/kanban/config wrapper that reads dashboard.kanban preferences from config.yaml, writing redacted receipts.

Inputs: no named parameters. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_dispatch_nudgeNudge Kanban dispatcherB

Typed POST /api/plugins/kanban/dispatch wrapper that nudges the kanban dispatcher to skip the 60 s wait, with optional max, dry_run, board, and tenant query params, writing redacted receipts.

Inputs: max, board, tenant, dry_run. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_orchestration_getGet Kanban orchestration settingsC
Read-onlyIdempotent

Typed GET /api/plugins/kanban/orchestration wrapper that reads kanban orchestration settings and resolved effective values, writing redacted receipts.

Inputs: resolve. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_orchestration_updateUpdate Kanban orchestration settingsB

Typed PUT /api/plugins/kanban/orchestration wrapper that updates orchestrator_profile, default_assignee, or auto_decompose in config.yaml, writing redacted receipts.

Inputs: auto_decompose, default_assignee, orchestrator_profile. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_profiles_listList Kanban profilesC
Read-onlyIdempotent

Typed GET /api/plugins/kanban/profiles wrapper that lists installed Hermes profiles with descriptions, writing redacted receipts.

Inputs: limit, offset. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_profile_updateUpdate Kanban profile descriptionB

Typed PATCH /api/plugins/kanban/profiles/{name} wrapper that sets or clears a profile's user-authored description, writing redacted receipts.

Inputs: name (required), description. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_run_getGet Kanban runA
Read-onlyIdempotent

Typed GET /api/plugins/kanban/runs/{run_id} wrapper that reads single-run detail such as task id, status, started/ended timestamps, exit code, and log path, writing redacted receipts.

Inputs: run_id (required). Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_run_inspectInspect Kanban run outputA
Read-onlyIdempotent

Typed GET /api/plugins/kanban/runs/{run_id}/inspect wrapper that reads per-run captured output (stdout/stderr preview, redacted), writing redacted receipts. Process control remains unwrapped/denied.

Inputs: run_id (required). Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_task_comment_createCreate Kanban task commentB

Typed POST /api/plugins/kanban/tasks/{id}/comments wrapper that appends a comment to a Kanban task, using JSON body for the comment text and optional board query param, writing redacted receipts.

Inputs: id (required), body (required), board. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_task_createCreate Kanban taskB

Typed POST /api/plugins/kanban/tasks wrapper that creates a Kanban task with title, body, assignee, priority, parents, triage flag, idempotency key, and workspace options, writing redacted receipts.

Inputs: title (required), body, board, skills, +9 more. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_task_decomposeDecompose Kanban taskA

Typed POST /api/plugins/kanban/tasks/{id}/decompose wrapper that runs the kanban decomposer auxiliary LLM to produce a task graph, create children, link the root, and flip triage to todo, writing redacted receipts.

Inputs: id (required), board. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_task_getGet Kanban taskA
Read-onlyIdempotent

Typed GET /api/plugins/kanban/tasks/{id} wrapper that reads one Kanban task by id with optional board slug and tenant, writing redacted receipts.

Inputs: id (required), board, tenant. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_tasks_bulk_updateBulk update Kanban tasksA

Typed POST /api/plugins/kanban/tasks/bulk wrapper that applies the same status, assignee, priority, archive, or completion patch to every id in the list, reporting per-id outcomes without aborting siblings, writing redacted receipts.

Inputs: ids (required), board, result, status, +6 more. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_task_specifySpecify Kanban taskA

Typed POST /api/plugins/kanban/tasks/{id}/specify wrapper that runs the triage specifier auxiliary LLM to flesh out a triage task and promote it to todo, writing redacted receipts.

Inputs: id (required), board. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_task_updateUpdate Kanban taskA

Typed PATCH /api/plugins/kanban/tasks/{id} wrapper that updates status, assignee, priority, title, body, result, or completion summary for one Kanban task, writing redacted receipts.

Inputs: id (required), body, board, title, +7 more. Returns: Standard MCP tool result envelope for future tools.

hermes_kanban_workers_activeList active Kanban workersA
Read-onlyIdempotent

Typed GET /api/plugins/kanban/workers/active wrapper that lists currently spawned Kanban workers with PID, profile, task id, and heartbeat metadata, writing redacted receipts.

Inputs: no named parameters. Returns: Standard MCP tool result envelope for future tools.

hermes_log_tailTail allowlisted Hermes logA
Read-onlyIdempotent

Tail a configured allowlisted log path with bounded reads and redaction; arbitrary log paths are denied.

Inputs: log_name (required), home, lines, profile, +2 more. Returns: Standard MCP tool result envelope for future tools.

hermes_profiles_listList Hermes profilesA
Read-onlyIdempotent

List local Hermes profiles and profile-local surface presence without exposing memory, skill, plugin, or config contents.

Inputs: home, profile, toolkit_root. Returns: Standard MCP tool result envelope for future tools.

hermes_skill_eval_startStart Hermes skill eval jobC

Validate a skill id/read boundary, then start a bounded dry/live-gated eval job without writing the skill file.

Inputs: suite (required), skill_id (required), home, model, +10 more. Returns: Standard MCP tool result envelope for future tools.

hermes_skill_patch_applyApply gated Hermes skill patchB

Apply an exact-scope skill-file patch only when mutation policy, allow_skill_write, expected sha256, and confirmation nonce gates all pass; writes a private backup and receipt artifact.

Inputs: reason (required), skill_id (required), new_string (required), old_string (required), +8 more. Returns: Standard MCP tool result envelope for future tools.

hermes_skill_patch_proposalWrite Hermes skill patch proposalA

Write proposal-only skill patch artifacts after bounded skill-file readback; performs no skill writes or git operations.

Inputs: skill_id (required), new_string (required), old_string (required), home, +5 more. Returns: Standard MCP tool result envelope for future tools.

hermes_skill_readRead Hermes skill fileA
Read-onlyIdempotent

Read one bounded SKILL.md or linked skill file after resolving the skill and linked file within allowed roots.

Inputs: skill_id (required), home, source, profile, +3 more. Returns: Standard MCP tool result envelope for future tools.

hermes_skills_listList Hermes skillsA
Read-onlyIdempotent

List Hermes toolkit/profile skill directories and linked-file inventories without reading profile memory, writing skills, or invoking evals.

Inputs: home, limit, detail, offset, +2 more. Returns: Standard MCP tool result envelope for future tools.

hermes_status_overviewHermes status overviewA
Read-onlyIdempotent

Aggregate read-only Hermes install, profile, toolkit, config, and API configuration metadata without live prompt-bearing calls.

Inputs: home, profile, toolkit_root. Returns: Standard MCP tool result envelope for future tools.

hermes_toolkit_infoHermes toolkit infoA
Read-onlyIdempotent

Summarize toolkit agents, skills, eval harness paths, suites, helper scripts, and README metadata without reading secrets.

Inputs: home, profile, toolkit_root. Returns: Standard MCP tool result envelope for future tools.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 73 tools

    Disambiguation3/5

    There is significant overlap in several areas: hermes_skill_patch_proposal vs hermes_skill_patch_apply are distinct, but hermes_skill_eval_start vs hermes_eval_start vs hermes_eval_run vs hermes_api_runs_start all involve 'starting evals/runs' and could be confused. Similarly, hermes_status_overview and hermes_toolkit_info and hermes_detect_install and hermes_config_summary all aggregate overlapping read-only metadata. The docs_list/docs_read pair for API and Kanban API are parallel but distinguishable. The naming clearly delineates domains (skill vs config vs api vs kanban vs eval), but within domains several tools have similar purposes the agent may struggle to distinguish.

    Naming Consistency4/5

    Tool names follow a consistent hermes_<domain>_<verb>_<noun> pattern throughout, using snake_case uniformly. The prefix structure is predictable (hermes_api_*, hermes_kanban_*, hermes_skill_*, hermes_eval_*), which helps agents navigate. Minor inconsistency: some use get vs read (hermes_api_models_list vs hermes_skill_read vs hermes_kanban_task_get), and _list vs _*_get conventions vary slightly, but the overall pattern is highly consistent and readable.

    Tool Count2/5

    73 tools is far above the typical well-scoped range of 3-15, and this is a very heavy surface. While the server has broad breadth (install, config, skills, API wrappers, Kanban, evals, jobs, gateway), 73 tools will impose substantial cognitive load on agents when selecting, and many could be consolidated (e.g., the read-only status/toolkit/info/detect aggregation tools overlap heavily, and the 7 jobs_* tools and 8 kanban_task_* tools could be trimmed). At 73, even with broad scope, this is too many.

    Completeness4/5

    Within the domains covered, there's strong lifecycle coverage: jobs have create/get/update/list/delete/pause/resume/run; Kanban tasks have create/update/get/comments/bulk/run_decompose; API responses have create/get/delete; runs have start/get/stop/events/approval. The addition of an agent_ask_fallback plus docs tools shows thoughtful coverage. Minor gaps exist—there's no explicit Kanban task delete, no board create/delete tool despite board_get/list, and no Kanban comments list/delete—but the core workflows are well covered. The eval surface has run/start/status/cancel which is complete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      MCP sidecar for Hermes Agent exposing operator tools (cron, skills, config, workspace) with tiered read-only/operator/owner modes and dry-run by default for safe local development.
      43
      1
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A local, evidence-driven MCP runtime and control plane for open-source maintainers that provides workspace-bounded tools including controlled file operations, command execution, validation primitives, durable execution records, and human review workflows via stdio and Streamable HTTP transports.
      33
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server exposing scoped, read-only enterprise operations tools with fail-closed credential handling. It returns opaque approval IDs for mutations and requires a separate operator approval command to release one-time capabilities.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables governed remote execution of Hermes Agent tasks over MCP with client authentication, RBAC, audit logging, and human-in-the-loop approvals.
      -