rp-herdr-core-mcp
OfficialThis server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
rp-herdr-core-mcp
A small single-user MCP adapter for herdr-core (tested: 0.1.15, 0.1.16, 0.1.17), using the official MCP SDK. Version 0.2.0. MIT licensed. macOS/Linux; no Windows pipe support.
Six tools expose configured cores: list_hosts, list_sessions, read_output,
send_prompt, opt-in create_session, and opt-in press_escape. No extra LLM or arbitrary-shell tool.
Legacy local configuration stays restricted. Named hosts and broad trusted-core
creation require explicit operator configuration/approval; see MULTIHOST.md.
Unix connections never start core. An explicitly approved SSH hc connect bridge
may auto-start its selected core; no core shutdown/update is exposed. Output is
untrusted data and may contain secrets.
Quick start
Use Node.js 22+ and an existing supported hc installation:
npm ci --ignore-scripts
npm run check
npm run test:integrationCopy examples/config.stdio.json to a private location outside the repository,
set the actual absolute socketPath, and keep sendAllowlist: [] initially.
The example path is not discovery: HC_SOCKET, hc config, XDG directories and the
selected session can change the endpoint. Do not move core state or replace sockets.
node scripts/inspect-core.js /absolute/private/config.jsonThis probe prints core ID and terminal lifetime metadata. Configure your
MCP host using examples/mcp.json, replacing all absolute paths. Run Node directly
for stdio, not npm, so package-manager output cannot pollute protocol stdout.
Discover the tools and verify list/screen reads before enabling writes. SSH probes may auto-start core only when explicitly opted in.
See AGENT-HANDOFF.md for migration and verification.
Related MCP server: herdr-mcp
Tools and bounds
list_hosts: configured public host/profile IDs and independent availability; failures remain visible, with no fallback or private connection details.
create_session: trusted-core only, configured agent/project/variant aliases, stable request ID, startup verification and no adapter-added initial prompt.
list_sessions: local terminal records, optionally finished, paginated at 25 by default (maximum 100). Non-atomic snapshot; no reconstructed chat history.
read_output: current screen only, last 12,000 characters by default (maximum 32,768), with truncation/completeness flags. Always
lines: 0: hc history stitching can inject scrolling input, so it is deliberately not exposed.send_prompt: paste text and submit using the terminal's configured key (Enter by default). Maximum 16,000 characters; terminal control characters rejected. Never
force, never waits for task completion, never automatically retries.
Core connections are capped at eight per host (at most 16 hosts), received bytes at 1 MiB per call, and timeout
at 15 seconds by default (configurable 100–60,000 ms). Large upstream lists can
exceed the byte limit before pagination; this fails explicitly. The adapter checks
JSON-RPC IDs and reply shape, generation 1, plain framing, required methods, and
configured core identity. Versions 0.1.15, 0.1.16 and 0.1.17 are reviewed. Other
well-formed older/newer versions warn on stderr and proceed after those checks;
version alone is not a rejection for the original tools. Escape is stricter:
press_escape retains its reviewed 0.1.15/0.1.16 gate and rejects all other versions. Mutation errors on untested versions remain
unknown outcomes, including status_mismatch: inspect before retrying. Warnings
are emitted once per untested version per CoreClient (bounded to 16 versions).
Shutdown closes adapter connections only; existing terminals continue.
Approving writes and send modes
In default restricted access, sending requires an operator-approved terminal address and creation timestamp plus the actual core ID from the probe. Keep private config outside Git. Example:
{
"socketPath": "/absolute/private/existing.sock",
"transport": "stdio",
"coreId": "COPY-ACTUAL-CORE-ID",
"sendMode": "normal",
"sendAllowlist": [{ "address": "t1b", "created_ms": 1234567890000 }]
}sendMode is operator configuration, not a caller-controlled tool argument:
Mode | Behavior |
| Existing behavior: always sends with core's atomic |
| Preflight must report |
Normal mode is not an atomic idle-or-done guarantee. These hc versions only accept
idle or working in if; done is not expressible. After a done preflight the
program may become working before input arrives. Core serializes input, waits for
keyboard quiet and refuses blocked programs, but does not wait for task completion.
Normal-mode approval accepts that race. Results expose send_mode,
preflight_status, and atomic_status_guard (null when absent), as well as core's
observed send status. No false idle report, interruption, forced send or core fork
is used. Pi normally reports done after successful work, so idle-only is too
restrictive for that follow-up workflow.
Only approve dedicated trusted agent terminals. Core ID and creation timestamp checks mitigate stale-ID reuse, but do not authenticate the executable. OSC 7501 status is self-reported; a terminal's foreground program can change. A prompt can cause the downstream agent to execute commands or change files. Approval grants that program's effective authority; never repurpose an approved terminal as a shell.
Read before each consequential follow-up. A successful send is not task completion.
The exact validated core status_mismatch rejection (-32000, after the pinned
handshake) is labeled NOT SENT because core rejects it before input writes.
Other post-dispatch errors/timeouts remain conservatively UNKNOWN. Neither
classification triggers automatic replay; inspect and make a fresh decision.
Cancellation during preflight prevents a subsequent send; cancellation after
submission cannot undo terminal input.
Optional authenticated HTTP
examples/config.http.json enables stateless MCP Streamable HTTP at /mcp, bound
only to 127.0.0.1. Supply a private HERDR_MCP_TOKEN of at least 32 high-entropy
bytes through your existing secret environment; missing or placeholder credentials
fail startup closed. No credential is generated or included by this project.
Remote use requires operator-managed HTTPS proxy/private transport. Preserve
Authorization and configured Host; reject untrusted forwarding headers, disable
sensitive logging/caching, and apply connection/rate limits. Never expose raw hc
sockets or a plaintext public listener. Every /mcp request requires bearer auth;
Host/Origin validation runs first and request bodies are capped at 64 KiB.
Only exact GET/HEAD probes to /.well-known/oauth-protected-resource/mcp and
/.well-known/oauth-protected-resource return unauthenticated 404, without a
challenge: the documents are unsupported. Other paths/methods remain protected.
This is not an OAuth authorization server. A client choosing “No authentication” will not supply HTTP bearer credentials. Clients requiring OAuth need a separately configured compatible gateway; never remove auth to work around incompatibility. An authenticated tunnel that owns a local stdio process is an alternative only if its access controls are independently verified. Stdio uses process access instead of HTTP bearer auth; it does not authorize an unprotected public HTTP endpoint.
Verification and provenance
See VALIDATION.md for performed checks and limitations and PATCH-NOTES.md for changes. No deployment or live integration is implied by passing mocked tests.
Verified core contract: tag v0.1.15, commit
9e934dff8513710d3c5111fe28bc5b23564805db, plus reviewed tag v0.1.16
(e07c2a1bedd62cf4787ee026ee23ee79c7d95491) and v0.1.17
(ce87721557176f6cddaac1c7aefbf76929923263). See
the 0.1.17 compatibility review for semantic changes and risks:
The adapter does not depend on oldherdrTUI. Review and test source/schema changes before adding another version to the reviewed set. Untested versions warn by default.
Multiple hosts and creation
See MULTIHOST.md for explicit host IDs/core pins, strict SSH bridging, restricted versus trusted-core policy, configured Pi/Claude profiles, model/provider argument variants, exact project directories, creation verification and uncertainty. No actual host is configured or enabled by installing this source.
Optional MCP Events
See EVENTS.md for opt-in discovery, durable subscription storage, webhook delivery, replay, configuration requirements and polling limits.
Desktop workspace placement
An operator may configure desktopSpaces on an agent profile, mapping an existing
project ID to a Herdr desktop workspace ID, for example
"desktopSpaces": { "demo": "workspace-demo" }. IDs contain 1–128 ASCII letters,
digits, underscores or hyphens and start with a letter or digit. Only configured
projects may be mapped; the mapping is optional and does not change tool inputs.
Creation includes the configured workspace as the herdr.space terminal label
in the initial terminal.run request. Receipts expose desktop_space and
desktop_visibility_requested; these describe placement metadata, not proof that
a desktop window rendered the terminal. No desktop document or existing terminal
is rewritten. Reconciliation retains an existing terminal's placement even if the
operator later changes the mapping, and cached receipts remain explicitly stale.
Escape cancellation
The opt-in press_escape tool supports one exactly approved Escape cancellation.
It is disabled by default and requires a separate expiring terminal/screen approval.
See ESCAPE.md for the policy, state-race limits, and mandatory readback.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Termalin's hosted MCP server. Claude, ChatGPT or any MCP client runs commands, moves files over SFTP, queries databases and reads server metrics and monitoring alerts on your servers, keylessly through Termalin Connectors: no SSH key is handed over and no inbound port is opened. Per-host command policy and an audit log. Needs a termal.in Pro or Team account (new accounts start with a 14-day Pro trial).
SSH client, server management and one remote MCP URL for your machines, with human approvals.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables MCP hosts to connect to local Codex sessions for listing, reading, messaging, and interrupting them without hijacking the terminal.1MIT
- AlicenseBqualityBmaintenanceEnables MCP clients to remotely control a running Herdr session: see agent status, arrange tabs and panes, start and prompt coding agents, and run worktree-isolated jobs over stdio or Streamable HTTP. Includes policy controls such as allowlists, read-only mode, disabled tools, and an audit log.322MIT
- AlicenseNot gradedqualityBmaintenanceConnects remote AI agents and other MCP clients to a running Herdr session, enabling them to list terminal panes, check output, send tasks, and wait for status changes.5MIT
- AlicenseBqualityCmaintenanceEnables MCP clients to observe and control a running Herdr session by inspecting panes, agents, layouts, and live lifecycle events, and by prompting agents, waiting for completion, running commands, and managing workspaces, tabs, panes, and worktrees.411MIT