herdr-mcp

MCP server for herdr: one read-only tool per herdr method, over streamable HTTP with a bearer token.

Contents

• What it does

• Prerequisites

• Install

• Usage

• Configure a client

• Tools

• Configuration

• Exit codes and failure modes

• Security scope

• Run as a service

• Use as a library

• Support

• License

• Maintainers

• Contributing

Related MCP server: herdr-mcp

What it does

• Serves one MCP tool per read-only herdr structure method. The tool name is herdr_ plus the method with dots turned into underscores (pane.list becomes herdr_pane_list). Every tool is annotated readOnlyHint: true, destructiveHint: false and idempotentHint: true.

• Terminal content, long-poll methods, event subscriptions, writes, control and admin methods are never exposed. The tool set is computed from the herdr SDK's method table (ADR-0001).

• Streamable HTTP transport with MCP protocol versions 2025-11-25, 2025-06-18 and 2025-03-26. Tools only: no resources, prompts or sampling.

• Every request must carry Authorization: Bearer <token>. The server listens on loopback (127.0.0.1) by default.

Prerequisites

• Bun 1.4.4 or later. The server uses Bun's HTTP server, so it does not run on Node. Check with bun --version.

• A running herdr server with its unix socket. The socket is resolved in this order: HERDR_MCP_SOCKET, then the SDK's own resolution (HERDR_SOCKET, then ~/.config/herdr/herdr.sock). The SDK targets herdr 0.9.5 (socket protocol 22).

The server starts without a herdr socket. Tool calls then return an error result until herdr is reachable (see Exit codes and failure modes).

Install

bun add -g @stateforge-labs/herdr-mcp

The package provides the herdr-mcp command. Bun runs its TypeScript source directly, so there is no build step. Development checks are described in CONTRIBUTING.md.

Usage

Start the server:

herdr-mcp

It prints the listen address and nothing else:

herdr-mcp: listening on http://127.0.0.1:7423

On the first start the bearer token is created in the token file (see Configuration). The token is never printed. Read it with:

cat ~/.local/state/herdr-mcp/token

A minimal call: initialize a session, then call a tool. The session ID comes back in the Mcp-Session-Id response header.

TOKEN="$(cat ~/.local/state/herdr-mcp/token)"
H=(-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
   -H "Accept: application/json, text/event-stream" -H "MCP-Protocol-Version: 2025-11-25")

SID=$(curl -s -D - -o /dev/null http://127.0.0.1:7423/mcp "${H[@]}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"example","version":"0.0.0"}}}' \
  | tr -d '\r' | awk -F': ' 'tolower($1)=="mcp-session-id"{print $2}')

curl -s http://127.0.0.1:7423/mcp "${H[@]}" -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"herdr_workspace_list","arguments":{}}}'

Sample output (abridged; the workspace names and IDs depend on your herdr):

{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"type\":\"workspace_list\",\"workspaces\":[{\"workspace_id\":\"w1\",\"number\":1,\"label\":\"example\",\"focused\":true,\"pane_count\":1,\"tab_count\":1,\"active_tab_id\":\"w1:t1\",\"agent_status\":\"unknown\"}]}"}]}}

Tool arguments are checked against each tool's input schema before herdr is called. Unknown keys and missing required keys are rejected with isError: true and a text that starts with invalid params:.

Configure a client

The server speaks streamable HTTP only. Clients that support only stdio servers cannot connect to it directly. Keep the token in your environment, not in a file that is committed.

Claude Code

Put this in the project's .mcp.json:

{
  "mcpServers": {
    "herdr": {
      "type": "http",
      "url": "http://127.0.0.1:7423/mcp",
      "headers": { "Authorization": "Bearer ${HERDR_MCP_TOKEN}" }
    }
  }
}

Export the token in the shell that starts the client:

export HERDR_MCP_TOKEN="$(cat ~/.local/state/herdr-mcp/token)"

VS Code

Put this in .vscode/mcp.json, with HERDR_MCP_TOKEN exported in the environment VS Code starts from:

{
  "servers": {
    "herdr": {
      "type": "http",
      "url": "http://127.0.0.1:7423/mcp",
      "headers": { "Authorization": "Bearer ${env:HERDR_MCP_TOKEN}" }
    }
  }
}

Change the port in url if HERDR_MCP_PORT is set.

Tools

All tools take a JSON object and reject keys that are not listed (additionalProperties: false). string or null parameters accept null to mean "not given". Every tool has readOnlyHint: true, destructiveHint: false and idempotentHint: true. On success a tool returns herdr's result as structuredContent and as JSON text in content; a non-object result is wrapped as { "result": ... }. On failure it returns isError: true with a text.

The table is generated from the method table of @stateforge-labs/herdr-sdk. A method is listed when its class is a structure read (R-meta), it is not a long poll, and it is not events.subscribe.

Configuration

The program reads only environment variables. A bad value stops the program with a message that names the setting, never its value.

A malformed token file is replaced at startup, so every client must read the token again after a restart.

Exit codes and failure modes

The program exits with status 1 on every startup failure. No other exit status is defined.

Security scope

• What an agent that holds the token can read: the structure reads in the Tools table. These cover workspaces, tabs, panes, agents, layouts, integrations and plugins, plus process information for panes (pane.process_info) and plugin logs (plugin.log.list). Those last two can contain data from your session, so check them before you expose the port.

• What it cannot do: write, send input, run actions, read terminal content, open event subscriptions, or call admin methods. None of these methods is in the tool set.

• Network: the server listens on 127.0.0.1 by default. Setting HERDR_MCP_HOST to another interface exposes it to that network. The server speaks plain HTTP with no TLS, so the bearer token is the only guard, and it crosses the network unencrypted.

• Token: kept in a 0600 file inside a 0700 directory. Compared in constant time. Never logged or printed. The listen line and the request log are disabled. To rotate it, stop the server, delete the token file and start the server again.

To report a vulnerability, see SECURITY.md.

Run as a service

systemd/herdr-mcp.service is a user unit with the sandboxing and loopback defaults described above. It starts ~/.bun/bin/herdr-mcp, the command that bun add -g installs by default. Install the package, copy the unit from the installed package to ~/.config/systemd/user/, then run:

bun add -g @stateforge-labs/herdr-mcp
mkdir -p ~/.config/systemd/user
cp ~/.bun/install/global/node_modules/@stateforge-labs/herdr-mcp/systemd/herdr-mcp.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now herdr-mcp

If Bun is installed somewhere else, or BUN_INSTALL is set, change the ExecStart path in the copied unit to the herdr-mcp command that bun add -g installed.

Use as a library

The package exports the server, its HTTP layer and the auth helpers. Import them from @stateforge-labs/herdr-mcp:

A runnable host program, the same as src/main.ts without the environment reading:

import { Effect, Layer } from "effect"
import { HerdrMcpLive, tokenFile } from "@stateforge-labs/herdr-mcp"

const token = await tokenFile({ path: "/absolute/path/to/token" }).readOrCreate()
const server = HerdrMcpLive({ host: "127.0.0.1", port: 7423, token })

await Effect.runPromise(Layer.launch(server) as Effect.Effect<never, unknown, never>)

Run it with bun run host.ts in a project that depends on the package, where host.ts is the file above. Pass socketPath to HerdrMcpLive to use a socket other than the default.

Support

Ask questions and report bugs in GitHub issues. For security problems, use SECURITY.md instead of a public issue.

License

MIT. See LICENSE.

Maintainers

Maintained by stateforge-labs.

Contributing

See CONTRIBUTING.md for how to report bugs, set up the project, and propose changes.