home / mcp / herald mcp server

Herald MCP Server

Self-hosted MCP bridge that connects Claude Chat to Claude Code for remote work sessions and code execution.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "btouchard-herald": {
      "url": "https://herald.yourdomain.com/mcp"
    }
  }
}

Herald is a self-hosted MCP server that bridges Claude Chat to Claude Code over the official Custom Connectors protocol. It lets you orchestrate code chores from any device, so you can draft a changelist, run tests, and push results without being tied to a single workstation or browser tab.

How to use

You connect Claude Chat to Herald using a built‑in MCP connector. Once linked, you can start tasks in Claude Code from your phone or laptop, monitor progress, and pull back summaries, file changes, and git branches back into Claude Chat. Tasks run in isolation on their own branches, and you can resume multi‑turn conversations or remote sessions from any device.

How to install

Prerequisites: you need a domain with HTTPS and access to Claude Code. You will also run Herald as a native binary or via Docker. Follow these steps to install and run Herald.

curl -fsSL https://raw.githubusercontent.com/btouchard/herald/main/install.sh | sh
```

<details>
<summary>Or build from source (requires Go 1.26+)</summary>

```bash
git clone https://github.com/btouchard/herald.git
cd herald && make build
# Binary is in ./bin/herald
```
</details>

Configuration and startup

Create a config directory and a configuration file. Then run Herald so Claude Chat can connect and start managing Maven-style tasks.

server:
  host: "127.0.0.1"
  port: 8420
  public_url: "https://herald.yourdomain.com"

auth:
  client_id: "herald-claude-chat"

projects:
  my-api:
    path: "/home/you/projects/my-api"
    description: "Main backend API"
    default: true
    allowed_tools:
      - "Read"
      - "Write"
      - "Edit"
      - "Bash(git *)"
      - "Bash(go *)"
      - "Bash(make *)"
    git:
      auto_branch: true
      branch_prefix: "herald/"
```

Connect Claude Chat to Herald at the MCP URL shown after first start, such as `https://herald.yourdomain.com/mcp`. Authenticate via OAuth and you will see the new tools appear in Claude Chat.

Using with Claude Chat and Claude Code

After linking, you can start a task from Claude Chat and watch Herald chore the work in Claude Code. You’ll receive a task ID immediately, with status updates and eventual results including a summary, differing files, and any git changes.

# Start a task by sending a request from Claude Chat
# Claude Code runs in the background and pushes updates to Herald
```

```json
{
  "task": "start_task",
  "project": "my-api",
  "operation": "Refactor auth middleware",
  "branch_prefix": "herald/"
}
```

Use Claude Chat to check progress and retrieve the final results when ready.

Security and best practices

Herald remains self-contained on your network. It binds to localhost by default, with TLS termination handled by a reverse proxy. It uses OAuth 2.1 with PKCE, rotating tokens, and per‑project tool restrictions to limit what Claude Code can do within each project.

Configuration notes

The configuration supports multiple projects, per‑project tool restrictions, and a rotation of access tokens. Edit the YAML to add projects, define allowed tools, and control Git behavior. Low‑level details are designed to keep your main branch safe while enabling rapid iteration.

Deployment options

Herald is shipped as a single Go binary and can be run directly or via Docker. If you use Docker, you can pair Herald with Traefik or Caddy for TLS termination and expose the MCP endpoint at a public domain.

# Docker Compose snippet (example)
services:
  herald:
    image: herald:latest
    volumes:
      - "~/.config/herald:/root/.config/herald"
      - "~/projects:/root/projects:ro"
    environment:
      - HERALD_DOMAIN=herald.yourdomain.com

Troubleshooting and tips

If Claude Chat cannot connect, verify the MCP URL is reachable, TLS is handled by your proxy, and tokens are valid. Check logs for OAuth issues, token rotation, or rate limit messages. Ensure the domain is accessible and the reverse proxy forwards to port 8420.

Tools you get with Herald

Herald exposes a set of MCP tools that Claude Chat discovers automatically. These tools let you start tasks, monitor progress, fetch results, manage sessions, and inspect code changes.

Notes on MCP configuration references

To connect Claude Chat, configure the MCP endpoint at your domain with the path /mcp and complete the OAuth flow to authorize Claude Chat to invoke tasks on Herald.

Available tools

start_task

Launch a Claude Code task. Returns an ID immediately and supports priority, timeout, session resumption, and Git branch options.

check_task

Check status and progress. Optionally include recently produced output.

get_result

Retrieve the full result of a completed task, with options like summary, full, or json.

list_tasks

List tasks with filters such as status, project, and time range.

cancel_task

Cancel a running or queued task and optionally revert Git changes.

get_diff

Show a Git diff for a task's branch or uncommitted changes.

list_projects

List configured projects with their Git status.

read_file

Read a file from a project with path safeguards to prevent escaping the project root.

herald_push

Push a Claude Code session to Herald for remote monitoring and continuation from another device.

get_logs

View logs and activity history.