adeelahmad · Oct 11, 2026 · Oct 11, 2026 · Oct 11, 2026 · Oct 11, 2026 · Oct 11, 2026
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -19,7 +19,7 @@ body:
       options:
         - HTTP proxy
         - WebDriver
-        - MCP (planned)
+        - MCP
         - Remote UI (planned)
         - Core / sessions
         - Docs / tooling
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -57,7 +57,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `--token` or `--insecure-allow-public`, bearer/basic token auth, a
   loopback Host/Origin guard against DNS rebinding, a per-session domain
   allowlist policy seam, and log redaction of tokens and cookies.
-- MCP and remote-browser UI faces as documented stubs on the shared core.
+- MCP server face at `/mcp` (Streamable HTTP; MCP 2025-06-18, 2025-03-26 and
+  2024-11-05) with 16 browser tools: tabs, navigation, accessibility-style
+  snapshots with stable element refs, click, type, keys, select, scroll,
+  wait, JavaScript, screenshots and in-tab `fetch()` with the user's cookies.
+  Shares tabs, auth, the loopback guard and `--allow-domains` with the other
+  faces; `--mcp=false` turns it off. See `docs/MCP.md`.
+- `tether mcp`: a stdio bridge for MCP clients that don't speak HTTP
+  (Claude Desktop, IDEs), local or across a tailnet.
+- Remote-browser UI face as a documented stub on the shared core.
+- Screenshots of idle background tabs no longer hang: Tether brings the tab
+  to the front and retries, as ChromeDriver does (WebDriver and MCP).
 - Sprint Zero: Makefile, golangci-lint, CI (lint → test + coverage →
   build matrix → govulncheck), CodeQL, Dependabot, GoReleaser (archives,
   checksums, multi-arch Docker image, Homebrew cask), community docs.

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -34,7 +34,8 @@ Read [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) first. In short:
 | `internal/core` | The engine every face calls: `Do`, `Eval`, `Navigate`, `Policy` |
 | `internal/proxy` | HTTP/HTTPS forward-proxy face |
 | `internal/webdriver` | W3C WebDriver face |
-| `internal/mcp`, `internal/remote` | Planned faces (stubs) |
+| `internal/mcp` | MCP face and stdio bridge |
+| `internal/remote` | Planned face (stub) |
 | `internal/server`, `internal/api` | Listener, auth, guard, control API |
 
 Faces stay thin. If a change needs browser logic, it almost certainly

diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 ### Your logged-in Chrome — as a proxy, from anywhere. No extension.
 
 **Give your AI agent (or your script, or your other laptop) your real, logged-in browser.**<br/>
-One self-contained binary. Speaks plain HTTP proxy and WebDriver. Drives Chrome over the DevTools Protocol.
+One self-contained binary. Speaks MCP, plain HTTP proxy and WebDriver. Drives Chrome over the DevTools Protocol.
 
 [![CI](https://github.com/adeelahmad/tether/actions/workflows/ci.yml/badge.svg)](https://github.com/adeelahmad/tether/actions/workflows/ci.yml)
 [![Go Report Card](https://goreportcard.com/badge/github.com/adeelahmad/tether)](https://goreportcard.com/report/github.com/adeelahmad/tether)
@@ -31,9 +31,12 @@ Chrome already speaks, and turns each tab into something any client can use:
   storage, real JavaScript. You get the rendered page back.
 - 🤖 **A WebDriver endpoint.** Point Selenium at it and most scripts just
   work — against your actual signed-in profile.
-- 🧩 **One core, four faces.** The proxy and WebDriver ship today; an MCP
-  server for agents and a live remote-browser UI are designed in and
-  stubbed ([architecture](docs/ARCHITECTURE.md)).
+- 🧠 **An MCP server for agents.** Claude, Cursor or your own agent get
+  tools to read, click, type, screenshot and fetch in your real browser
+  ([docs/MCP.md](docs/MCP.md)).
+- 🧩 **One core, four faces.** Proxy, WebDriver and MCP ship today on the
+  same tab sessions; a live remote-browser UI is designed in and stubbed
+  ([architecture](docs/ARCHITECTURE.md)).
 - 🔒 **Safe by default.** Loopback-only unless you set a token. Built to sit
   on a private [Tailscale](https://tailscale.com) tailnet, not the internet.
 
@@ -73,8 +76,9 @@ screen for everyone else. 🎉
 
 ```mermaid
 flowchart LR
-  A["curl / requests / agent"] -- "HTTP proxy" --> T
+  A["curl / requests"] -- "HTTP proxy" --> T
   B["Selenium"] -- "WebDriver" --> T
+  D["AI agent"] -- "MCP" --> T
   T["tether serve<br/>sessions · policy · auth"] -- "DevTools Protocol" --> C
   subgraph C["Your Chrome (logged in)"]
     T1["tab: github.com"]
@@ -126,6 +130,19 @@ Responses carry `X-Tether-Tab-ID`, `X-Tether-Final-URL` (after redirects)
 and, on errors, a stable `X-Tether-Error` code (`tab_gone`, `forbidden`,
 `navigation_failed`, `timeout`, …).
 
+### MCP (AI agents)
+
+```sh
+claude mcp add --transport http tether http://127.0.0.1:8787/mcp
+```
+
+Then ask: *"Open my GitHub notifications and summarise what needs me."* The
+agent gets `browser_navigate`, `browser_snapshot`, `browser_click`,
+`browser_type`, `browser_screenshot`, `browser_fetch` and more, all in your
+signed-in Chrome. Claude Desktop and other stdio clients use the bundled
+bridge (`"command": "tether", "args": ["mcp"]`). Setup for every client,
+the full tool list and the security notes: [docs/MCP.md](docs/MCP.md).
+
 ### WebDriver
 
 ```python
@@ -201,6 +218,7 @@ Every flag has a `TETHER_*` environment variable; flags win.
 | `--policy-file` | — | JSON file with per-token rules and tokens — see [docs/POLICIES.md](docs/POLICIES.md) |
 | `--data-dir` | user config dir | Local CA and launched profile |
 | `--no-mitm` | `false` | Refuse HTTPS `CONNECT` instead of intercepting |
+| `--mcp` | `true` | Serve the MCP face at `/mcp` |
 | `--log-level`, `--log-format` | `info`, `text` | `json` for machines; secrets are always redacted |
 
 Docker (headless Chromium inside the image):
@@ -220,7 +238,7 @@ local CA, and it only drives Chromium-family browsers.
 | Needs a browser extension | **No** | Yes | No | No |
 | Plain HTTP proxy (curl, any language) | ✅ | ❌ | Rarely | ❌ |
 | W3C WebDriver / Selenium | ✅ incl. frames, alerts, windows, uploads, PDF | ❌ | Often | ✅ |
-| MCP for agents | Planned | Often | Often | Via wrappers |
+| MCP for agents | ✅ | Often | Often | Via wrappers |
 | Runs entirely on your machine | ✅ | ✅ | ❌ | ✅ |
 | Remote access | Tailscale + token | Usually local only | ✅ | DIY |
 | Single static binary | ✅ | ❌ | n/a | ❌ (driver + runtime) |
@@ -231,7 +249,7 @@ local CA, and it only drives Chromium-family browsers.
 - [x] Tab-session core, HTTP/HTTPS proxy, WebDriver common set, control API
 - [x] WebDriver Actions: hover, drag and drop, key chords, wheel, multi-touch
 - [x] Safe-by-default exposure, token auth, domain allowlist seam
-- [ ] MCP server face (tools over the same core) — stubbed at `/mcp`
+- [x] MCP server face: 16 browser tools over the same core, plus a stdio bridge
 - [ ] Remote-browser UI with live screencast and input — stubbed at `/remote`
 - [x] Per-token and per-session domain policies, enforced in the browser ([docs/POLICIES.md](docs/POLICIES.md))
 - [x] Per-tab console and browser log capture (control API + WebDriver `get_log`)

diff --git a/SECURITY.md b/SECURITY.md
@@ -67,9 +67,10 @@ a sandbox against a determined attacker who also shares the browser profile
 | Token leaks via logs | Redacting log handler; secrets never logged | Tokens passed on the command line are visible in `ps`; prefer `TETHER_TOKEN` or `--token-file`. |
 | Token leaks via `curl -x http://user:token@…` history | — | Shell history; prefer `--proxy-header "Proxy-Authorization: Bearer $TETHER_TOKEN"`. |
 | Local CA key theft | Key written `0600` in the per-user config dir | Anyone with your user account already has your browser. Only trust the CA in clients that use Tether; don't add it to your OS trust store unless you understand the implication. |
-| An agent/script navigates somewhere it shouldn't | Global, per-token and per-tab rules, checked in the core and enforced in the browser for top-level navigations (including redirects, clicks and script) | Subresources and `fetch()` from page script are not restricted; give agents `"scripts": false`. |
+| An agent/script navigates somewhere it shouldn't | Global, per-token and per-tab rules, checked in the core and enforced in the browser for top-level navigations (including redirects, clicks and script); MCP tools also check the page's current URL before reading or acting on it | Subresources and `fetch()` from page script are not restricted; give agents `"scripts": false`. |
 | One agent reads or steers another agent's tab | Per-token ownership: non-admin tokens only resolve their own tabs, including via cookie, header and WebDriver session ID | Admin tokens see everything by design. |
 | Tether used to read a page the user has open | Only tabs Tether opened, or tabs explicitly addressed by ID, are driven; adopting requires an admin token | Any admin token can address any tab by ID. |
+| Prompt injection: a web page steers an AI agent connected over MCP | Server instructions tell the model page content is untrusted; tool annotations mark destructive tools; `--allow-domains` bounds where it can go; password values and `Set-Cookie` are never returned | An agent with access to your browser can be talked into acting as you. Use an allowlist and a client that confirms destructive tool calls. See [docs/MCP.md](docs/MCP.md#security). |
 | Chrome DevTools port exposed | `--launch` binds it to loopback; Tether never re-exposes it | If you start Chrome yourself with `--remote-debugging-address=0.0.0.0`, that is outside Tether's control. |
 | A client attaches local files to a page (WebDriver file inputs) | Clients are fully trusted (see above); remote uploads land in a per-session temp dir deleted when the session ends | A token holder can make a page upload any file the Tether user can read. |
 | Automation rearranges the person's screen | Window resize/maximise/minimise/fullscreen only act on windows holding nothing but Tether tabs | — |

diff --git a/cmd/tether/main.go b/cmd/tether/main.go
@@ -11,19 +11,22 @@ import (
 	"io"
 	"os"
 	"os/signal"
+	"strings"
 	"syscall"
 
 	"github.com/adeelahmad/tether/internal/app"
 	"github.com/adeelahmad/tether/internal/certs"
 	"github.com/adeelahmad/tether/internal/config"
 	"github.com/adeelahmad/tether/internal/logx"
+	"github.com/adeelahmad/tether/internal/mcp"
 	"github.com/adeelahmad/tether/internal/version"
 )
 
 const usage = `tether — your logged-in Chrome, as a proxy, from anywhere. No extension.
 
 Usage:
-  tether serve [flags]   start the proxy + WebDriver server
+  tether serve [flags]   start the proxy, WebDriver and MCP server
+  tether mcp [flags]     bridge a stdio MCP client (Claude Desktop, IDEs) to a running Tether
   tether ca [--data-dir]  print the local CA certificate path (trust it for HTTPS)
   tether version         print version information
 
@@ -47,6 +50,8 @@ func run(args []string, stdout, stderr io.Writer) int {
 		return 0
 	case "ca":
 		return ca(args[1:], stdout, stderr)
+	case "mcp":
+		return mcpBridge(args[1:], os.Stdin, stdout, stderr)
 	case "help", "-h", "--help":
 		fmt.Fprint(stdout, usage)
 		return 0
@@ -87,7 +92,11 @@ func serve(args []string, stdout, stderr io.Writer) int {
 	)
 	fmt.Fprintf(stdout, "\n  Tether %s is serving %s on http://%s\n", version.Version, a.Browser, a.Addr)
 	fmt.Fprintf(stdout, "  Proxy:     curl -x http://%s --cacert <(curl -s http://%s/tether/v1/ca.pem) https://example.com\n", a.Addr, a.Addr)
-	fmt.Fprintf(stdout, "  WebDriver: http://%s  (Selenium remote URL)\n\n", a.Addr)
+	fmt.Fprintf(stdout, "  WebDriver: http://%s  (Selenium remote URL)\n", a.Addr)
+	if cfg.MCP {
+		fmt.Fprintf(stdout, "  MCP:       http://%s/mcp  (claude mcp add --transport http tether http://%s/mcp)\n", a.Addr, a.Addr)
+	}
+	fmt.Fprintln(stdout)
 
 	if err := a.Serve(ctx); err != nil {
 		log.Error("server stopped", "err", err)
@@ -118,3 +127,41 @@ func ca(args []string, stdout, stderr io.Writer) int {
 	fmt.Fprintln(stdout, certs.CertPath(*dir))
 	return 0
 }
+
+// mcpBridge runs `tether mcp`: stdio on one side, Tether's /mcp endpoint on
+// the other. stdout carries protocol messages only; diagnostics go to stderr.
+func mcpBridge(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
+	fs := flag.NewFlagSet("tether mcp", flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	env := func(k, def string) string {
+		if v, ok := os.LookupEnv(k); ok {
+			return v
+		}
+		return def
+	}
+	url := fs.String("url", env("TETHER_MCP_URL", "http://"+config.DefaultAddr+mcp.Prefix), "Tether MCP endpoint [$TETHER_MCP_URL]")
+	token := fs.String("token", env("TETHER_TOKEN", ""), "Tether bearer token [$TETHER_TOKEN]")
+	tokenFile := fs.String("token-file", env("TETHER_TOKEN_FILE", ""), "read the bearer token from this file [$TETHER_TOKEN_FILE]")
+	if err := fs.Parse(args); err != nil {
+		if errors.Is(err, flag.ErrHelp) {
+			return 0
+		}
+		return 2
+	}
+	if *tokenFile != "" && *token == "" {
+		b, err := os.ReadFile(*tokenFile)
+		if err != nil {
+			fmt.Fprintln(stderr, "tether:", err)
+			return 2
+		}
+		*token = strings.TrimSpace(string(b))
+	}
+	log, _ := logx.New(stderr, "warn", "text")
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+	if err := mcp.Bridge(ctx, mcp.BridgeOptions{URL: *url, Token: *token, Logger: log}, stdin, stdout); err != nil {
+		fmt.Fprintln(stderr, "tether mcp:", err)
+		return 1
+	}
+	return 0
+}
diff --git a/cmd/tether/main_test.go b/cmd/tether/main_test.go
@@ -20,6 +20,9 @@ func TestRun(t *testing.T) {
 		{[]string{"bogus"}, 2, "", "unknown command"},
 		{[]string{"serve", "--token", "short"}, 2, "", "at least 16"},
 		{[]string{"serve", "-h"}, 0, "", "-insecure-allow-public"},
+		{[]string{"serve", "-h"}, 0, "", "-mcp"},
+		{[]string{"mcp", "-h"}, 0, "", "TETHER_MCP_URL"},
+		{[]string{"mcp", "--token-file", "/nonexistent/token"}, 2, "", "tether: open"},
 		{[]string{"serve", "--addr", "0.0.0.0:0", "--chrome", "127.0.0.1:1"}, 1, "", "refusing to listen"},
 	}
 	for _, tt := range tests {

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -20,7 +20,7 @@ flowchart LR
     G[auth · loopback guard · recover]
     P[Proxy face<br/>HTTP + CONNECT/MITM]
     W[WebDriver face<br/>W3C common set]
-    M[MCP face<br/><i>stub</i>]
+    M[MCP face<br/>Streamable HTTP tools]
     R[Remote UI face<br/><i>stub</i>]
     A[Control API<br/>/tether/v1]
     subgraph core[core]
@@ -35,7 +35,7 @@ flowchart LR
 
   C1 --> G --> P
   C2 --> G --> W
-  C3 -.-> G -.-> M
+  C3 --> G --> M
   C4 -.-> G -.-> R
   G --> A
   P & W & M & R & A --> E
@@ -50,7 +50,7 @@ flowchart LR
 
 | Package | Role |
 |---|---|
-| `cmd/tether` | CLI: `serve`, `ca`, `version`. Parses config, wires logging and signals. |
+| `cmd/tether` | CLI: `serve`, `mcp` (stdio bridge), `ca`, `version`. Parses config, wires logging and signals. |
 | `internal/app` | Assembles a running Tether from a `Config`: Chrome, core, faces, server. Used by the CLI and the integration tests. |
 | `internal/cdp` | The only package that speaks CDP. `Browser` and `Tab` interfaces; `Chrome` implementation over a single flattened websocket; endpoint discovery and `Launch`. `cdptest` holds fakes. |
 | `internal/session` | `Session` = one page target. `Manager` resolves requests to sessions, opens/adopts/closes tabs, reaps idle ones, and serialises work per tab. |
@@ -60,7 +60,8 @@ flowchart LR
 | `internal/webdriver` | W3C WebDriver face (see [WEBDRIVER.md](WEBDRIVER.md)). |
 | `internal/api` | Control plane: health, whoami, tabs, tab policies, eval, CA download. |
 | `internal/server` | Listener, routing, per-token auth, loopback guard, graceful shutdown, exposure checks. |
-| `internal/mcp`, `internal/remote` | Planned faces, mounted and answering `501` today. |
+| `internal/mcp` | MCP face: Streamable HTTP transport, per-agent sessions, browser tools, and the stdio bridge (see [MCP.md](MCP.md)). |
+| `internal/remote` | Planned face, mounted and answering `501` today. |
 | `internal/certs`, `internal/logx`, `internal/config`, `internal/version`, `internal/httpx` | Supporting pieces. |
 
 ## The session model
@@ -148,7 +149,7 @@ proxy auth and Tether control headers never reach the page.
 |---|---|---|
 | HTTP proxy | **Shipping** | `Sessions.Resolve`, `Core.Do` |
 | WebDriver | **Shipping** | `Sessions.Create/Get/Close`, `Core.Navigate`, `cdp.Tab` primitives |
-| MCP server | Stub (`/mcp` → 501) | Will map tools (`navigate`, `read_page`, `click`, `type`, `eval`, `screenshot`, `tabs`) onto the same calls. Each agent authenticates with its own token, so per-token policies and tab ownership apply unchanged. Streamable HTTP transport on the same listener, so it inherits auth and Tailscale exposure. |
+| MCP server | **Shipping** | `Sessions.Create/Get/Close`, `Core.Navigate`, `Core.Eval`, `Core.Do` (fetch mode), `core.Policy`, `cdp.Tab` primitives. Streamable HTTP on the same listener, so it inherits auth and Tailscale exposure. Each MCP session tracks one current tab and the tabs it opened; `core.Policy` is checked against the page's current URL before every page tool. Each agent authenticates with its own token, so per-token policies and tab ownership apply unchanged. |
 | Remote UI | Stub (`/remote` → 501) | Will stream a tab with `Page.startScreencast` (WebRTC later) and forward input through `cdp.Tab.Click`/`Key`, letting a person watch or take over exactly the tab an agent is driving. |
 
 Every face implements `core.Face` (`Name()` + `http.Handler`) and is mounted