<p align="center"><img src="img/logo_nbg.png" width="50%"></p>

Herald MCP

Herald lets the AI assistants on several of your computers talk to each other and work together.

Say you use Claude Code on your laptop, and you also have an office PC and a home server. With Herald, the Claude on your laptop can:

• run a command on the office PC and read the result (exec_shell),
• ask the AI on the home server to do a job and answer back (ask_peer),
• send files to, and receive files from, any of them (send_file, deposit_file).

The PCs do not need public IPs or open router ports. They reach each other over Tailscale, a free private network, through one small message hub called the relay.

Claude and GPT, on different computers, working as one team

This is the point of Herald: the AIs do not have to come from the same vendor or sit on the same machine. Herald is in daily use on a network of several Windows PCs where:

• Claude Code runs on several of the PCs, and the Claude on the main PC directs the others: runs

commands on them, asks their Claude to do a job, collects files and results;

• GPT runs on another PC, through OpenAI's Codex CLI. The Claude on the main PC hands it a coding

task through Herald, Codex does the work on its own machine, and the result comes back to Claude.

   Main PC  ── Claude Code (directs the work)
      │
      │  Herald, over Tailscale
      ├──────────►  Server PC      ── Claude Code   "check the scan log and fix the error"
      ├──────────►  Accounting PC  ── Claude Code   "export this month's report"
      └──────────►  Another PC     ── Codex CLI / GPT   "write and test this module"

Why that matters: most multi-agent tools run every agent on one machine, and usually from one vendor. MCP itself connects an AI to tools on its own computer. Herald fills the gap between them: it is the wire that lets an AI on one computer reach an AI on another, whatever model each one runs. That means each job can go to the machine that holds the data, the licence or the hardware, and to the model that is best at it.

What each side needs:

[!IMPORTANT] Herald needs the AI's command-line tool (CLI), not just its desktop app. A PC with only the Claude Desktop or ChatGPT app installed cannot answer ask_peer or take work from other PCs: Herald starts the claude / codex program, and the ChatGPT app's agent runs in a sandbox that cannot reach the rest of the PC. In past installs exactly this was missed, and those PCs silently never answered. setup.bat now installs the CLI and has you log in; see Before You Start.

Handing a task to Codex from another PC looks like this (Codex is started through python, which the default allowlist permits; it needs --dangerously-bypass-approvals-and-sandbox because its own sandbox cannot start inside the tray's background process):

exec_shell(peer_name="gpt-pc", timeout=180, cmd="python -c \"import subprocess; subprocess.run('codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check -C C:\\work -', shell=True, input='Write and test parser.py')\"")

Table of Contents

• Claude and GPT, on different computers, working as one team
• Key Concepts
• Before You Start
• Installation
• Option A — Let an AI Agent Install It (recommended)
• Option B — Install by Hand
• Check That It Works
• Troubleshooting
• Starting and Stopping Herald
• System Tray UI
• Why Herald MCP?
• Architecture
• Security
• Files

Key Concepts

Read this once; the installer will ask you about each of these.

             Office PC                 Home server
           (client: leno)             (client: dv)
                  \                       /
                   \   Tailscale (100.x)  /
                    \                   /
                 +----------------------------+
                 |  Relay PC (also a client)  |
                 |  April: server.py + tray   |
                 +----------------------------+
                               |
                          Your laptop
                    (client + controller: cc)

Install order: first the relay PC (its installer prints the relay URL and token), then each of the other PCs with role join, using that URL and token.

Before You Start

Prepare these first, so the installation runs straight through:

1. Windows 10 or 11 on every PC, and an account that can approve an administrator prompt (needed

once, to install Tailscale). The tray is Windows-only.

1. A Tailscale account. Sign up free at <https://login.tailscale.com/start>. You can sign in with

a Google, Microsoft or GitHub account.

1. Decide which PC hosts the relay. Pick one that stays on most of the time. If it is off, the

other PCs cannot reach each other.

1. Decide how the PCs will see each other on Tailscale. Either:

• log every PC into the same Tailscale account (simplest), or
• use separate accounts, and have the relay PC's owner share the relay machine with the other

accounts: <https://login.tailscale.com/admin/machines> → ... on the relay machine → Share.

1. A peer name for each PC (default: its lower-case Windows computer name).
2. Decide which AI CLI each PC gets, and have its account ready. The installer installs the CLI

itself; you only log in. The desktop apps (Claude Desktop, ChatGPT) do not count.

The installer takes care of the rest: git, Python 3.12, Tailscale, the Python packages and the AI CLIs you choose are installed automatically if they are missing.

Installation

There are two ways. Both give the same result. Do the relay PC first, then the others.

Option A — Let an AI Agent Install It (recommended)

If the PC already has a coding agent with shell access (the Code tab of Claude Desktop, Claude Code, Antigravity, Codex CLI), let it do the work. The repository's CLAUDE.md has a step-by-step script written for agents: it asks you every question up front, installs the prerequisites and the AI CLIs (Claude Code, Codex), runs the setup wizard without prompts, and checks the result.

Paste this to the agent on the PC you are installing:

Install Herald MCP on this PC by following the "AI installers" section of https://github.com/liewcc/Herald_MCP/blob/master/CLAUDE.md. This PC is the relay of a new network. (or:) This PC joins an existing network.

The agent cannot do the parts that need you in person. Expect to:

• click Yes on the Windows administrator prompt when Tailscale is installed;
• log in to Tailscale in the browser page that opens;
• log in to the AI CLI: run claude auth login (and/or codex login) in a terminal when the agent asks;
• share the relay machine on Tailscale, if the PCs use different accounts;
• relay PC: copy the relay URL and token the agent reports, and keep them for the other PCs;
• joining PC: paste that URL and token into the chat when the agent asks.

[!NOTE] Sandboxed agents (for example the ChatGPT desktop app) cannot install software on the real PC. The agent checks for this first and tells you to use Option B instead.

Option B — Install by Hand

#### Step 1 — Tailscale on every PC

setup.bat installs Tailscale for you, but the login and the sharing are yours to do:

1. On each PC, log in to Tailscale with your account (tray icon → Log in). If Tailscale is not

installed yet, setup.bat installs it and opens the sign-in page for you in Step 2.

1. Make sure the PCs can see each other: same account on every PC, or the relay machine shared with

the other accounts (see Before You Start, item 4).

1. Check from a command prompt: tailscale ip -4 shows this PC's 100.x.x.x address, and

tailscale status lists the other PCs.

#### Step 2 — Install the relay PC

1. Download the repository: green Code button → Download ZIP, then extract it to a permanent

folder, e.g. C:\AI\Herald_MCP. Do not run it from the Downloads folder: autostart points at this location.

1. Double-click `setup.bat`. It checks git, Python and Tailscale and installs what is missing (approve

the administrator prompt for Tailscale), then installs the Python packages.

1. AI CLI. If the Claude Code CLI is missing, setup asks Install it? → y (Enter). It then asks

whether to install the Codex CLI too → y only if this PC should run GPT. For each CLI that is installed but not logged in, a browser page opens: sign in, then come back to the setup window. Setup prints [OK] Claude Code CLI, logged in (and the same for Codex) when it worked.

1. The setup wizard starts. Answer:

• Is this PC hosting the relay for a NEW network, or joining? → 1 (relay)
• Peer name → e.g. April
• Peers this PC will talk to → the names of the other PCs, comma-separated (you can leave it blank

and add them later)

• Generate a new token? → y
• Write it? → y (the wizard shows the settings first)
• Start Herald automatically at logon? → y for a PC that should always be reachable

1. When it finishes, the wizard prints a line like this. Copy it somewhere safe, every other PC needs it:

   role = join, URL = http://100.101.102.103:7700, token = 3f9c…(64 characters)

1. If this PC is also a controller, answer y when setup.bat offers to register Herald with Claude

Code / Antigravity.

The relay PC now runs two things: the relay (server.py) and its own tray.

#### Step 3 — Install each of the other PCs

1. Download and extract the repository as in Step 2.
2. Double-click `setup.bat`. Install and log in to the AI CLI as in Step 2, item 3, then answer the

wizard:

• Hosting or joining? → 2 (join)
• Peer name → e.g. leno
• Peers this PC will talk to → e.g. April
• Relay URL → the URL from the relay PC, e.g. http://100.101.102.103:7700
• Relay token → the token from the relay PC

1. The wizard tests the URL and token before writing anything. If the test fails, it explains what

to fix and lets you retry (see Troubleshooting).

1. Confirm Write it?, answer the autostart question, and on controller PCs let setup.bat register Herald with Claude Code

/ Antigravity.

#### Step 4 — Restart the AI on controller PCs

Restart Claude Code (or Antigravity) so it loads the Herald tools.

Check That It Works

• A Herald icon is in the Windows system tray of every PC. Open it, go to the Network tab: each PC

that is running should be a green box (see System Tray UI).

• From a controller PC, ask the AI: "Use exec_shell to run `hostname` on leno." It should answer with

that PC's computer name.

• For a PC with Claude Code and Auto Reply on: "Use ask_peer to ask leno what day it is." Its Claude

should answer within about a minute.

To change settings later (another relay, new peers, a new name), run python setup_wizard.py again instead of editing config.json by hand.

Troubleshooting

Running your own relay on a cloud server instead of a PC? See docs/admin-setup.md.

Starting and Stopping Herald

Herald starts automatically at logon if you chose autostart. To start it by hand: python herald_tray.py (on the relay PC also python server.py).

To stop it: right-click the tray icon → Exit. This closes the connection to the relay at once; the PC receives nothing from other PCs until the tray runs again.

[!NOTE] Closing the tray = zero inbound exposure. While the tray runs it keeps an outbound connection to the relay, which can push commands to this PC at any time. allowlist.json decides which shell commands other PCs may run here; keep it as tight as you can.

System Tray UI

The tray window has four tabs (Messages, Comm Log, Remote Tasks, Network) and switches for autostart, Auto Reply and notifications. See docs/system-tray-ui.md.

Why Herald MCP?

Herald MCP occupies a unique "Personal Bridge" niche: it turns a private computer into a reachable, AI-accessible node via a persistent, self-hosted relay. Unlike agent frameworks (which manage AI logic) or sandboxed environments (which manage security isolation), Herald focuses purely on remote accessibility — allowing frontier AIs to interact directly with your real local environment via MCP tools.

What it is not: Herald is a minimal agent communication and transport layer — it provides multi-agent delegation, tool execution, and message relaying via MCP, but does not manage reasoning, planning, or memory (those are delegated to the connected AI, e.g. Claude). It is also not sandboxed: commands run directly on the host shell. The tray daemon is Windows-only; Linux/Mac require manual startup.

Architecture

Herald MCP is designed as a federated communication system where multiple local instances communicate via a stateless, central relay (on one of your PCs, or on a cloud server). This architecture eliminates the need for peer-to-peer port forwarding, firewall traversal, or local server hosting.

                           +-----------------------------+
                           |        Cloud Server         |
                           |         (server.py)         |
                           +--------------+--------------+
                                          ^
                          HTTP/SSE Pull   |   HTTP Post Ask/Reply
                          & Push Events   |   & File Deposits
                                          v
                          +---------------+--------------+
                          |      Your Windows Host       |
                          +------------------------------+
                          |                              |
                          |   +----------------------+   |
                          |   |   herald_tray.py     |   |
                          |   | (System Tray Daemon) |   |
                          |   +-----------+----------+   |
                          |               |              |
                          |       Spawns  v Background   |
                          |   +----------------------+   |
                          |   |      claude.exe      |   |
                          |   |    (Claude Code)     |   |
                          |   +-----------+----------+   |
                          |               |              |
                          |       Starts  v StdIO        |
                          |   +----------------------+   |
                          |   |    mcp_server.py     |   |
                          |   |     (MCP Server)     |   |
                          |   +----------------------+   |
                          |                              |
                          +------------------------------+

1. Component Overview

2. Message Delivery Model

Herald uses SSE-based push with work-queue semantics — each message goes to exactly one subscriber.

When a local daemon starts, it opens a long-lived GET request to the server's /subscribe endpoint. The server maps each peer name to a single asyncio.Queue. When a message arrives for that peer, it is pushed onto the queue and streamed to the one active subscriber. If the connection drops, the daemon automatically reconnects with a 5-second back-off.

3. Execution Paths

Herald supports two communication pathways:

#### Path A — Direct Shell (exec_shell)

No AI needed on the remote side. The tray daemon executes the command directly in PowerShell after validating it against allowlist.json.

[Machine A]              [Cloud Server]           [Machine B Tray]
     |                         |                         |
     |-- POST /ask ----------->|                         |
     |   {type: "shell",       |                         |
     |    cmd: "..."}          |-- SSE push ------------>|
     |                         |                         | validate allowlist
     |                         |                         | run powershell
     |                         |<-- POST /reply ---------|
     |<-- stdout/stderr -------|                         |

#### Path B — AI Agent Round-Trip (ask_peer)

Used when the remote peer needs to reason, use tools, or produce a natural-language reply.

[Machine A]              [Cloud Server]           [Machine B Tray]
     |                         |                         |
     |-- POST /ask ----------->|                         |
     |   {message: "..."}      |-- SSE push ------------>|
     |                         |                         | spawn claude.exe
     |                         |                  [claude.exe subprocess]
     |                         |<-- GET /pending --------|
     |                         |--- message body ------->|
     |                         |                         | reason + tools
     |                         |<-- POST /reply ---------|
     |<-- reply answer --------|                         |

The spawned claude.exe is restricted to only mcp__herald__get_pending and mcp__herald__reply — it cannot access local files or run shell commands.

4. File Transfer

Direct file writes via exec_shell are typically blocked by the allowlist — use deposit_file instead.

5. Auto-Reply Lifecycle

When Auto Reply is enabled in the tray UI:

1. An incoming ask_peer message triggers the SSE handler in herald_tray.py.
2. The daemon checks whether a previous claude.exe subprocess is still running (single-instance guard). If busy, the message is queued.
3. A new claude.exe is spawned headlessly with -p (non-interactive) mode and a fixed --allowedTools list.
4. Claude fetches the pending message, formulates a reply, and calls reply() to close the round-trip.

6. Component Interaction: herald_tray.py vs mcp_server.py

These two processes serve opposite directions — one listens, one speaks.

Critical rule: mcp_server.py has zero inbound capability. Even if Claude Desktop is open, closing herald_tray.py means no remote peer can reach this machine.

Security

[!IMPORTANT] Herald MCP is a personal/hobbyist tool designed for trusted-machine scenarios (e.g., controlling your own second PC or connecting Claude on another machine you own). It is not commercial-grade P2P software, not designed for untrusted peers, and not a replacement for hardened enterprise remote-access tools like RDP or SSH.

Trust Model & Built-in Guards

Herald operates under a shared-secret trust model. It implements the following safeguards:

• Relay Token: server.py refuses to start without a token and rejects (401) every request without a matching X-Herald-Token header. All peers share the same token in config.json.
• Outbound-Only SSE: The client daemon in herald_tray.py initiates outbound connections; no inbound firewall ports are opened.
• Command Guard: exec_shell commands are parsed with PowerShell's own parser; only a single pipeline whose every element matches allowlist.json runs. ;, $(...), (...), {...}, variables, & and redirection are rejected.
• Restricted Auto-Reply: The daemon spawns claude.exe with --allowedTools restricted to get_pending and reply, preventing the remote agent from executing local commands or accessing local files.

Limitations & Non-Goals

• Shared Secret Only: Every token holder can impersonate any peer name; there is no per-peer identity.
• No Transit Encryption: Message payloads and file deposits are sent unencrypted (relying entirely on the relay server's TLS/HTTPS).
• Broad Rules: The default python and claude rules still permit arbitrary code for token holders.
• Stateless Relay: The cloud server.py stores all active messages and file deposits in-memory, readable by any token holder.

Recommended Mitigations

1. Use HTTPS: Run the relay server behind a reverse proxy (e.g., Caddy/Nginx) with TLS.
2. Minimize Allowlist: Keep commands in allowlist.json as restrictive as possible.
3. Exit Daemon When Idle: Right-click the tray icon → Exit when you no longer need remote access. For maximum control, uncheck Start on Login in the tray window — this removes the automatic Windows startup entry so the daemon does not launch on boot. With auto-start disabled, Herald is completely offline until you manually run herald_tray.py, giving you explicit control over when your machine is reachable.
4. Keep URL and Token Private: Do not publish your relay server URL or token. The relay is plain HTTP, so without TLS or a private network (e.g. Tailscale) the token can be sniffed.

Files