Bug: Paperclip MCP from Hermes fails out-of-the-box (missing default companyId + docker hostname not in allowlist)#83
Merged
Conversation
…_DEFAULT_COMPANY_ID as required The Hermes service in this compose calls Paperclip at http://paperclip:3100, so the docker service name 'paperclip' must be in PAPERCLIP_ALLOWED_HOSTNAMES or the API rejects every MCP call with 403. Make that the structural default. Also annotate PAPERCLIP_DEFAULT_COMPANY_ID in the .env templates so operators know it must be set before the Paperclip MCP plugin will work from inside Hermes — empty causes "companyId is required" errors mid-conversation. Fixes #82
Hermes filters the environment when spawning MCP subprocesses — only keys
listed in mcp_servers.<name>.env get forwarded. The previous template had no
env block on the paperclip MCP, so /opt/paperclip/mcp-paperclip/server.mjs
started with no PAPERCLIP_API_KEY and a default base URL of 127.0.0.1:3100.
From the Hermes container, 127.0.0.1:3100 has nothing listening, so every
tool call surfaced as "fetch failed" to the model (and the bot reported
"Paperclip isn't connecting right now" to the user).
Add a minimal env block that forwards the four envs the MCP server reads,
using ${VAR} placeholders that Hermes interpolates from os.environ at spawn
time (see tools/mcp_tool.py::_interpolate_env_vars).
Note: bootstrap-profiles.sh::sync_mcp_servers_from_template only ADDS
missing mcp_servers entries — it does not update existing ones. So this
template change fixes new deployments only; existing profile config.yaml
files need a separate per-profile patch to pick up the new env block.
Fixes #82
Previously sync_mcp_servers_from_template only copied template entries
that were ENTIRELY missing from a profile's config.yaml. If an entry
already existed (e.g. paperclip MCP from an older deployment), template
updates to its env block were silently ignored — operators had to patch
every profile by hand. That's exactly the recovery toil we just hit when
adding PAPERCLIP_API_KEY/PAPERCLIP_API_BASE/PAPERCLIP_DEFAULT_COMPANY_ID/
PAPERCLIP_PROFILE_SYNC_API_KEY to the paperclip MCP env block.
Extend the sync to also MERGE missing env keys onto existing entries:
- Template env keys not in the profile's env block are added.
- Existing env values in the profile are NEVER overwritten (preserves
operator customisations).
- Non-env fields on existing entries (command, args, timeout, etc.) are
still NEVER touched.
- Operation is idempotent — running the bootstrap again is a no-op once
the profile is in sync.
Net effect: next image rebuild + container restart will pick up template
env additions automatically, on every existing profile, without manual
intervention.
Fixes #82
|
❌ Merge gate failing — the following must be resolved before merging:
Branch protection on |
…default-envs # Conflicts: # hermes-runtime/scripts/bootstrap-profiles.sh
|
❌ PR-Issue link check failed Linked issue is closed or doesn't exist. Reference an open issue with |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #82
Summary
Every fresh template-agent spin-up hits stacked failures the first time a Hermes profile calls the Paperclip MCP plugin. This PR bakes the missing defaults into the template so the bug stops repeating.
What broke
Three issues, all on the path between Hermes and the Paperclip API:
mcp_servers.<name>.envget forwarded. The previoushermes-runtime/templates/config.yamlhad noenv:block on thepaperclipMCP, soserver.mjsstarted with no API key and defaulted to127.0.0.1:3100(nothing listening from the Hermes container) → every tool call surfaced asfetch failedto the model.paperclipis not in the default allowlist — Hermes is hardcoded to callhttp://paperclip:3100in compose.yaml:71, butPAPERCLIP_ALLOWED_HOSTNAMESdefaulted tolocalhost,127.0.0.1. Paperclip 403s withHostname 'paperclip' is not allowed.PAPERCLIP_DEFAULT_COMPANY_IDis left undocumented — the MCP plugin falls back to this env when the model doesn't passcompanyIdas an argument. Empty →companyId is requirederror mid-conversation. Operators have no way to know it must be set before the MCP plugin works.All three baked into the template means every new deployment from this repo repeats the bug.
Changes
hermes-runtime/templates/config.yaml: addenv:block to thepaperclipMCP server config that forwardsPAPERCLIP_API_KEY,PAPERCLIP_API_BASE,PAPERCLIP_DEFAULT_COMPANY_ID,PAPERCLIP_PROFILE_SYNC_API_KEYvia${VAR}placeholders (Hermes interpolates fromos.environat spawn time).compose.yaml: includepaperclipin the defaultPAPERCLIP_ALLOWED_HOSTNAMES— it's structural to how the Hermes service in this compose reaches Paperclip, not site-specific..env.example+.env.coolify.example: mirror the allowlist change in the example value, and add a comment block abovePAPERCLIP_DEFAULT_COMPANY_ID=flagging it as required-before-MCP-works.Found on
Genvest
agent-genvestCoolify deployment on 2026-05-22 — the Head of Customer Service Hermes profile tried to assign a Paperclip ticket via Telegram and reported "Paperclip isn't connecting right now". The underlying errors in the Hermes session log werecompanyId is required,Hostname 'paperclip' is not allowed, andfetch failed.Caveat — existing deployments
bootstrap-profiles.sh::sync_mcp_servers_from_templateonly ADDS missingmcp_serversentries to a profile'sconfig.yaml; it does NOT update existing ones. So this template change fixes new deployments only — existing profileconfig.yamlfiles keep their oldpaperclipMCP entry with noenv:block. The Genvest droplet was patched per-profile manually as part of the live fix.A follow-up to make
sync_mcp_servers_from_templatereconcile env blocks on existing entries would prevent the same recovery toil next time. Out of scope here — flagging for the in-flight MCP overlay design (story/84).Test plan
.env.example(or.env.coolify.example) withPAPERCLIP_DEFAULT_COMPANY_IDfilled in.hermes -p <profile> mcp test paperclip→ 8 tools discovered, no "Missing PAPERCLIP_API_KEY" warning inlogs/mcp-stderr.log.companyId is requiredorfetch failed.