# Agent Bridge

> End-to-end encrypted bridge between MCP-capable AI agents and a human's
> phone. The agent runs a local MCP server; a zero-knowledge relay routes
> ciphertext to the Agent Bridge phone app. Pairing is a QR code — no accounts.

## Install (MCP server)

Package: @paulmh/agentbridge-mcp (npm, MIT). Requires Node >= 20.

Claude Code:

    claude mcp add agent-bridge -- npx -y @paulmh/agentbridge-mcp --relay https://api.agent-bridge.app --name "My Agent"

Generic MCP JSON config:

    {
      "mcpServers": {
        "agent-bridge": {
          "command": "npx",
          "args": ["-y", "@paulmh/agentbridge-mcp", "--relay", "https://api.agent-bridge.app", "--name", "My Agent"]
        }
      }
    }

First run prints a pairing QR (also at ~/.agentbridge/default/pairing.html).
The human scans it with the Agent Bridge phone app. The QR contains the master
secret; never share or transmit it.

## Tools

- start_session: open a conversation thread on the phone
- ask_user: ask a question, optionally with tappable answer options (requires session_id)
- wait_for_reply: long-poll for answers/replies (timeout_seconds max 25; loop with the returned cursor)
- send_update: post progress updates into the thread
- notify: push a notification; optional public_title is all the lock screen shows
- request_oauth / poll_oauth: relay a third-party login to the phone; callback returns sealed to the bridge key
- get_upload: receive photos/files the human sends (encrypted client-side)
- report_processes: publish a live process/status board
- end_session, show_pairing

## Endpoints

- Relay API: https://api.agent-bridge.app
- WebSocket: wss://ws.agent-bridge.app (discovered via bridge.info; do not configure manually)
- OAuth callback: https://api.agent-bridge.app/oauth/cb

## Security

Master secret generated locally, transferred only via QR. HKDF derives a relay
bearer (routing only; stored as SHA-256 hash server-side) and an AES-256-GCM
content key the relay never sees. OAuth callbacks are sealed with the bridge's
X25519 key immediately on receipt. The relay stores ciphertext only.