Tether

Private, local-first browser control for AI assistants — your browser, your rules.

2. See It Work

Real-time execution: local daemon, Chrome MV3 extension, and governed MCP tool calls against test fixtures.

Related MCP server: Umbra MCP Server

3. What Tether Is

• A standard connector, not an autonomous agent: Your AI client (Claude, ChatGPT, Cursor) brings the reasoning; Tether enforces your rules.

• Single point of policy: Every action is decided inside the local extension service worker (TRD §2.3). Relays and daemons cannot grant permissions.

• Zero remote code (HR-1): Strictly Manifest V3. No eval, no remote CDNs, no runtime script fetching.

• Page content is untrusted data (HR-6): Extracted text carries trust: "untrusted"; prompt injection cannot trigger browser tools.

• Local OCR redaction: Screenshot text is scanned locally; PANs, tokens, and credentials are blacked out before returning image bytes.

• Sub-200ms hard kill switch (HR-10): Instantly terminates sockets, revokes tokens, and aborts in-flight actions.

Three Operating Modes (PRD §7.2)

4. Quick Start (Mode A)

git clone https://github.com/jyotitiwari250657/Tether-MCP-server.git
cd Tether-MCP-server && pnpm install && pnpm build
node apps/daemon/dist/index.js serve
# Chrome → Extensions → Developer Mode → "Load unpacked" → apps/extension/.output/chrome-mv3

Verify streamable HTTP MCP directly using curl:

# 1. Initialize MCP session (returns Mcp-Session-Id header)
curl -s -i -X POST http://127.0.0.1:18796/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0.1"}}}'
# → HTTP/1.1 200 OK | Mcp-Session-Id: a3f8… | {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18",…}}

# 2. List tools (returns 40 frozen tools)
curl -s -X POST http://127.0.0.1:18796/mcp -H "Content-Type: application/json" -H "Mcp-Session-Id: a3f8…" -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
# → {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"browser_snapshot",…},{"name":"browser_click",…}… 40 tools]}}

# 3. Call tool (snapshot active tab)
curl -s -X POST http://127.0.0.1:18796/mcp -H "Content-Type: application/json" -H "Mcp-Session-Id: a3f8…" -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"browser_snapshot","arguments":{}}}'
# → {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"# Acme Docs\n[A1] link \"Overview\"\n…"}]}}

5. Architecture

flowchart LR
    Client["AI Clients<br/>(Claude, ChatGPT, Codex, Cursor)"] --> Trans["Transport Layer<br/>stdio MCP / Streamable HTTP :18796 / Relay WSS"]
    Trans --> Daemon["Daemon / Relay"]
    Daemon -->|"loopback WS :18795"| SW["Extension Service Worker"]
    SW --> Policy["Policy Engine<br/>(Single Point of Policy)"]
    Policy --> CS["Content Script Bridge"]
    CS --> Page["Browser DOM Page"]
    SW --> Vault["Vault &rarr; OS Keychain"]
    SW --> OCR["OCR &rarr; Native Backend"]
    SW --> Audit["Audit &rarr; SHA-256 Hash Chain"]

Components

Anatomy of One Tool Call

1. Client Request: AI issues JSON-RPC tools/call over stdio or Streamable HTTP.

2. Daemon Auth: Daemon validates origin and auth token, packaging request into typed envelope.

3. Loopback Transport: Dispatched across WebSocket (:18795) to the Chrome MV3 service worker.

4. Policy Decision: engine.ts checks origin grant level; prompts diff card if Tier 2 (HR-8).

5. Ref Resolution: Element ref (e.g. A1) resolves to live DOM node via SHA-1 text signature.

6. Isolated Action: Synthetic input sequence (pointer, focus, click) executes safely in content script.

7. Redaction Pipeline: Output sanitized against PAN/email regex and native OCR redactor (HR-7).

8. Audit Seal: Write-ahead SHA-256 tamper-evident entry committed before returning result.

For deep dive, see docs/ARCHITECTURE.md.

6. Tool Surface

Tether exposes 40 frozen tools across three functional profiles:

7. Security & Governance

• Single Point of Policy (TRD §2.3): Policy is enforced strictly in apps/extension/lib/policy/engine.ts.

• Zero Plaintext on Wire: Mode B uses X25519 key exchange + AES-256-GCM authenticated envelopes.

• Zero Plaintext at Rest: Credentials resolve from OS Keychain (DPAPI / macOS Keychain / Secret Service).

• Default Deny (HR-12): Sensitive categories (banking, healthcare, auth) blocked until explicit opt-in.

• Absolute Kill Switch (HR-10): Aborts in-flight actions and revokes tokens in <200ms from popup or API.

• Tamper-Evident Audit & Local OCR: Chained SHA-256 log plus on-device OCR redaction of rendered PANs.

Read the THREAT_MODEL.md and SECURITY.md.

8. Proof & Quality Gates

Every metric below is verified directly from committed artifacts and live suites:

9. Repository Layout

tether/
├── apps/
│   ├── daemon/          # Node loopback WS server, stdio/HTTP MCP, keyring bridge
│   ├── extension/       # Chrome Manifest V3 extension (WXT + React 18)
│   ├── relay/           # Cloudflare Worker E2E encrypted routing
│   └── web/             # Astro + Starlight public documentation
├── packages/
│   ├── eval/            # 50-task automated evaluation suite
│   ├── ocr/             # Native OCR redactor bindings
│   └── protocol/        # Frozen schemas, envelopes, and tools (HR-4, HR-5)
├── tests/e2e/           # Playwright suites driving real browser & daemon
├── docs/                # Architecture, design system, specs & logs
└── scripts/             # Gate checks, asset composition, and bundle analyzers

10. Beta Status & Honest Limitations

1. Local Mode A is production-ready; Mode B relay is in active development.

2. Egress monitor is detect-only: Flags suspicious exfiltration patterns but does not drop packets.

3. Chromium-only in v1: Targets Manifest V3 on Google Chrome; Firefox and Safari deferred (NG-5).

4. WebMCP proxy requires Chrome 149+: Pre-release flags required for native in-page model tools.

5. ChatGPT Actions limitation: State-modifying POST requests require ChatGPT Enterprise/Business.

6. OCR native requirements: Uses Windows OCR / macOS Vision natively; fallback engine on Linux.

11. Documentation Index

12. Contributing, Security & License

• Contributing: Contributions welcome! Please review CONTRIBUTING.md before submitting pull requests.

• Security: Report vulnerabilities via GitHub Security Advisories or as detailed in SECURITY.md.

• License: Released under the MIT License © 2026 Tether Contributors.