herdr-core-mcp
This 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.
herdr-core-mcp
A remote MCP server that lets ChatGPT web see and talk to herdr-core terminals — coding agents like Claude Code, Codex and pi, plus plain shells — across the machines your core is federated with.
herdr-core speaks line-delimited JSON-RPC 2.0 over a Unix socket. ChatGPT's custom connectors only speak Streamable HTTP over HTTPS with OAuth 2.1 (no API keys). This project is the bridge:
ChatGPT (cloud) ──HTTPS──▶ Cloudflare Tunnel / any reverse proxy
│ 127.0.0.1:18790
▼
herdr-core-mcp ──unix socket JSON-RPC──▶ herdr-core
└─ federated machines (machine/t7)Tools
Tool | What it does | Access |
| List terminals across this core and federated machines, with filters | read-only |
| Status, turn, cwd, foreground process, labels, first-message delivery | read-only |
| Screen plus up to 200 lines of history, as plain text | read-only |
| Wait until idle, exit, or a specific string appears (≤ 40 s per call) | read-only |
| Federated machines and their connection state | read-only |
| Paste text and press Enter; refused while the terminal is | write |
| Press named keys ( | write |
| Press the stop key and report what happened | write |
There is deliberately no tool to start new terminals, run arbitrary commands, kill, or remove
terminals. Every write is appended to ~/.herdr-mcp/audit.log (mode 0600).
Related MCP server: ChatGPT VPS MCP
Security model
OAuth 2.1 only. Authorization code + PKCE S256, dynamic client registration, and a single owner password page. ChatGPT cannot send custom API keys, so this is the only safe way to expose write actions.
Terminal output is untrusted. Both the server instructions and every tool description tell the model to treat screen contents as data, never as instructions. Read tools are still a prompt-injection surface: only connect an account you trust.
Blocked terminals are never answered for you.
send_messagealways sendsforce: false, so a permission dialog has to be approved in Herdr by a human.Data leaves the machine. Terminal screens are sent to OpenAI. Do not point this at terminals that display secrets.
Optional hardening:
HERDR_MCP_READ_ONLY=1registers only the five read tools;HERDR_MCP_MACHINES=box-a,box-blimits reachable machines.
Quick start
npm install
npm test # wire vectors, fake core, full OAuth + MCP round trip
npm run buildRun locally against your own core:
export HERDR_MCP_OWNER_PASSWORD=dev
export HERDR_MCP_PUBLIC_URL=http://127.0.0.1:18790
npm run devSmoke-test a running server (local or public):
SMOKE_PASSWORD=dev npm run smoke -- --base http://127.0.0.1:18790
SMOKE_PASSWORD=dev npm run smoke -- --base https://mcp.example.com --terminal t7 --send "echo hi"Configuration
Variable | Default | Meaning |
|
| Bind address; keep it on loopback and expose it through a tunnel |
|
| Port |
|
| OAuth issuer and resource base; must equal the URL clients use |
|
|
|
| — | Overrides |
| host + public URL host | Host header allowlist |
|
|
|
| all | Comma-separated machine allowlist |
|
| Which herdr-core session to drive |
auth.json:
{ "ownerPassword": "…" }Keep it at mode 0600; generate with openssl rand -base64 24.
Deploy
Any always-on host that runs herdr-core (or can reach its socket) and has a public HTTPS entry point works. The included script targets macOS + launchd:
REMOTE=you@server PUBLIC_URL=https://mcp.example.com ./deploy/install.shIt builds locally, syncs to ~/herdr-core-mcp, runs npm ci --omit=dev, renders a launchd agent
(com.herdr-core-mcp by default), restarts it, and hits /healthz.
Then point a tunnel or reverse proxy at 127.0.0.1:18790. With Cloudflare Tunnel:
# ~/.cloudflared/herdr-core-mcp.yml
tunnel: <tunnel-id>
credentials-file: /home/you/.cloudflared/<tunnel-id>.json
ingress:
- hostname: mcp.example.com
service: http://127.0.0.1:18790
- service: http_status:404cloudflared tunnel create herdr-core-mcp
cloudflared --config ~/.cloudflared/herdr-core-mcp.yml tunnel route dns herdr-core-mcp mcp.example.com
cloudflared --config ~/.cloudflared/herdr-core-mcp.yml tunnel runtunnel route dns reads ~/.cloudflared/config.yml by default; pass --config explicitly or the
CNAME lands on the wrong tunnel. On networks where DNS is hijacked (fake-IP resolvers), cloudflared
may need --protocol http2 --edge <real-edge-ip>:7844.
Connect ChatGPT
Settings → Apps & Connectors → Advanced → enable Developer mode (paid plans).
Create → MCP server URL
https://mcp.example.com/mcp.Approve the OAuth page with the owner password.
In a chat:
+→ More → Developer mode → enable the connector. It has to be enabled per chat.
If the plan does not allow write tools, set HERDR_MCP_READ_ONLY=1 and restart; the connector then
advertises only the five read tools.
How it works
src/core/frames.ts,src/core/socket.ts— framed protocol and socket discovery, ported from Heeler's plugin helper (Apache-2.0). Wire vectors live intest/fixtures/.src/core/link.ts— one connection:hello {generation:1, framed:true}, then channel-0 JSON-RPC with request correlation, per-call timeouts, mutation outcome-unknown handling, and reconnect detection (core.idchange).src/http/oauth.ts,src/http/oauth-store.ts— single-user OAuth 2.1 provider on a 0600 JSON file; metadata endpoints come from the official MCP SDK.src/http/server.ts— Streamable HTTP at/mcp, session registry,/healthz.src/mcp/tools.ts— the eight tools above, with annotations, output caps and audit logging.
Troubleshooting
core_not_running— the core is not up, orHC_SESSIONpoints at another session.A new instance logs "listening" and exits immediately — another process holds the port;
lsof -nP -iTCP:18790 -sTCP:LISTEN, kill the orphan, then restart the agent.401 loop in ChatGPT —
HERDR_MCP_PUBLIC_URLdiffers from the URL in the connector, or the password is wrong.Machine not listed —
list_machinesshows the link state; federated machines are configured on the core (hc machine add), not here.Connection reset — the core restarted; the link reconnects on the next call.
License
Apache-2.0. See LICENSE and NOTICE. The protocol layer and wire vectors are derived from Heeler, also Apache-2.0.
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
Web search, data extraction and controlled browser automation for AI assistants via OAuth.
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).
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
OAuth 2.1 short-link tools for AI agents with scoped tokens, approvals, audit logs, and revocation.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables coding agents to control and inspect a running Herdr terminal session, including listing workspaces, tabs, panes, and agents, reading pane output, prompting agents, sending keys and commands, waiting for output or state, and splitting or closing panes.14-
- AlicenseNot gradedqualityBmaintenanceEnables ChatGPT to securely inspect and administer a Linux VPS over Streamable HTTP, with OAuth protection, workspace file tools, and optional root command execution.MIT
- FlicenseNot gradedqualityCmaintenanceEnables ChatGPT, Claude, and Cursor to securely manage a VPS through filesystem operations, system monitoring, and long-horizon command execution, protected by OAuth 2.1 with PKCE.-
- AlicenseNot gradedqualityBmaintenanceEnables ChatGPT to securely submit, monitor, and manage Hermes agent tasks and permission-gated Codex CLI jobs running on a local WSL2 machine.Apache 2.0