hotwired-mcp

MCP (Model Context Protocol) server for Hotwired multi-agent workflow orchestration.

Why Open Source?

This MCP server runs on your machine. We open source it so you can:

• Audit exactly what code runs on your machine
• Verify there are no external network calls
• Trust that there's no hidden behavior
• Build from source if you prefer

Hotwired.sh Architecture

Everything runs locally on your machine. There are no external service dependencies.

flowchart TB
    subgraph agents["AI Coding Agents"]
        claude["Claude Code"] ~~~ gemini["Gemini CLI"] ~~~ other["Other Agents"]
    end

    subgraph mcp["hotwired-mcp"]
        tools["MCP Tools"] --> ipc["IPC Client"]
    end

    subgraph desktop["Hotwired Desktop App"]
        socket["Unix Socket<br/>~/.hotwired/hotwired.sock"] <--> core["Hotwired Core"]
    end

    agents -->|"spawns"| mcp
    ipc <-->|"local only"| socket

How it works

1. Hotwired Desktop App runs locally and creates a Unix socket at ~/.hotwired/hotwired.sock
2. AI agents (Claude Code, Gemini, etc.) run hotwired-mcp as their MCP server
3. hotwired-mcp communicates with the desktop app via the local Unix socket
4. No external network calls - all communication stays on your machine

The only external connection the Hotwired Desktop App makes is for authentication. All workflow orchestration, message passing, and coordination happens entirely locally.

Installation

For Claude Code Users

Hotwired requires both the MCP server and the Claude Plugin for full functionality.

Step 1: Add the MCP server

claude mcp add hotwired -- npx @hotwired-sh/hotwired-mcp@latest

Step 2: Install the Claude Plugin

The plugin provides session hooks and slash commands that integrate Claude Code with Hotwired workflows:

claude plugin marketplace add hotwired-sh/claude-plugin
claude plugin install hotwired@hotwired-sh/claude-plugin

See the Hotwired Claude Plugin for more details.

For Other MCP-Compatible Agents

Add to your MCP configuration:

{
  "mcpServers": {
    "hotwired": {
      "command": "npx",
      "args": ["@hotwired-sh/hotwired-mcp@latest"]
    }
  }
}

Building from Source

If you prefer to audit and build the code yourself:

cargo install --git https://github.com/hotwired-sh/hotwired-mcp

Prerequisites

• Hotwired Desktop App - Must be running
• Zellij - Terminal multiplexer for session management

Available Tools

| Tool | Description | |------|-------------| | get_protocol | Fetch workflow protocol and role instructions | | get_run_status | Check current run status | | report_status | Update your working state | | send_message | Send message to other participants | | request_input | Ask human for input | | report_impediment | Signal you're blocked | | handoff | Hand work to another agent | | task_complete | Mark a task as complete |

Security

Why Unix Sockets (Not HTTP/localhost)

We deliberately use Unix sockets instead of HTTP on localhost. This is a critical security design choice.

Many MCP tools have been vulnerable to DNS rebinding attacks and 0.0.0.0 bypass exploits because they expose HTTP servers on localhost. These vulnerabilities allow malicious websites to:

• Send requests to localhost services via DNS rebinding
• Bypass browser same-origin policy through the 0.0.0.0 loophole
• Achieve remote code execution with no user interaction

Unix sockets are immune to these attacks:

• ❌ No TCP/HTTP listener - browsers cannot connect
• ❌ No DNS rebinding possible - not a network protocol
• ❌ No 0.0.0.0 bypass - sockets are filesystem-based
• ✅ Protected by filesystem permissions
• ✅ Only local processes can connect

What This MCP Server Does NOT Do

• Does NOT open any network ports - no HTTP, no TCP, no localhost
• Does NOT make any external network requests
• Does NOT read or modify files outside its scope
• Connects only to the local Unix socket (~/.hotwired/hotwired.sock)
• Source code is fully auditable

Development

# Build
cargo build --release

# Test
cargo test

# Run locally
cargo run

License

MIT - See LICENSE

Learn More

Visit hotwired.sh for documentation, tutorials, and more information about multi-agent workflow orchestration.