Serve HEY over MCP with hey mcp

.surface

@@ -252,6 +252,9 @@ hey login --cookie
 hey login --no-browser
 hey login --token
 hey logout
+hey mcp
+hey mcp --domains
+hey mcp --read-only
 hey move
 hey move --to
 hey reply

Makefile

@@ -55,6 +55,7 @@ help:
 	@echo ""
 	@echo "  make check-surface        Verify .surface matches the command tree"
 	@echo "  make update-surface       Regenerate .surface"
+	@echo "  make update-mcp-model     Refresh the vendored hey-sdk model snapshot for hey mcp (SDK=path)"
 	@echo "  make check-surface-compat Compare .surface against the previous release tag"
 	@echo "  make check-size           Check the built binary against .size-budget"
 	@echo "  make check-release-lockstep  Verify release tool pins and script references agree"
@@ -193,6 +194,12 @@ update-surface: check-toolchain
 	@HEY_NO_KEYRING=1 go test ./internal/cmd/ -run TestSurfaceSnapshot -count=1
 	@echo ".surface updated"
 
+# Refresh the vendored hey-sdk model snapshot the MCP catalog embeds
+# (internal/mcpserver/model/). Keep it in lockstep with the hey-sdk version
+# pinned in go.mod. SDK=path names a hey-sdk checkout (default ../hey-sdk).
+update-mcp-model:
+	@scripts/sync-mcp-model.sh $(SDK)
+
 # Compare .surface against the previous release tag (removals fail unless
 # acknowledged in .surface-breaking)
 check-surface-compat:

README.md

@@ -750,6 +750,32 @@ hey only ever writes skill directories it owns: each one it creates carries a
 `hey` skill directory (or symlink) without it — a hand-authored skill at one of those paths
 is never overwritten or claimed. `hey doctor` flags an unmanaged baseline and how to adopt it.
 
+### MCP server
+
+`hey mcp` runs an MCP (Model Context Protocol) server on stdin/stdout, serving HEY
+boxes, search, threads, contacts, todos, calendars, and your identity as tools
+backed by your signed-in account — the same keychain-stored credentials every other command uses.
+Register it with any MCP client as a stdio server:
+
+```bash
+claude mcp add hey -- hey mcp          # Claude Code
+hey mcp --read-only                    # serve only read-only actions
+hey mcp --domains boxes,search         # narrow the served tool surface
+```
+
+Each domain is one gateway tool (`hey_boxes`, `hey_search`, `hey_threads`,
+`hey_contacts`, `hey_todos`, `hey_calendar`, `hey_identity`) dispatching actions
+derived from the HEY SDK's API model; call an action named `describe` for any
+action's parameter schema. Listings with more pages come back as
+`{"next_page": cursor, "results": ...}` — pass the cursor back as the action's
+`page` parameter. The posting-changes feed's last page comes back as
+`{"next_since": ..., "next_v": ..., "results": ...}` — the cursor for the next
+incremental poll, passed back as the action's `since` and `v` parameters.
+Mutations are never retried automatically: a 429/503 on a write surfaces to
+the caller rather than risking a duplicate delivery, so retry a failed write
+yourself once you know it did not land. Logs go to stderr — stdout carries
+the MCP wire protocol.
+
 ## Troubleshooting
 
 ```bash

go.mod

@@ -9,11 +9,13 @@ require (
 	charm.land/lipgloss/v2 v2.0.6
 	github.com/basecamp/actioncable-go v0.0.0-20260824145920-822e6cf08655
 	github.com/basecamp/hey-sdk/go v0.28.0
+	github.com/basecamp/mcp v0.0.0-20260828100356-2d6f44b51e9d
 	github.com/charmbracelet/x/ansi v0.11.8
 	github.com/fsnotify/fsnotify v1.10.1
 	github.com/gofrs/flock v0.13.0
 	github.com/itchyny/gojq v0.12.19
 	github.com/mattn/go-runewidth v0.0.28
+	github.com/modelcontextprotocol/go-sdk v1.7.0
 	github.com/sigstore/sigstore-go v1.3.0
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/pflag v1.0.10
@@ -77,6 +79,7 @@ require (
 	github.com/godbus/dbus/v5 v5.2.2 // indirect
 	github.com/google/certificate-transparency-go v1.3.3 // indirect
 	github.com/google/go-containerregistry v0.21.7 // indirect
+	github.com/google/jsonschema-go v0.4.3 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/gorilla/css v1.0.1 // indirect
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0 // indirect
@@ -93,16 +96,20 @@ require (
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/secure-systems-lab/go-securesystemslib v0.11.0 // indirect
+	github.com/segmentio/asm v1.1.3 // indirect
+	github.com/segmentio/encoding v0.5.4 // indirect
 	github.com/shibumi/go-pathspec v1.3.0 // indirect
 	github.com/sigstore/protobuf-specs v0.5.1 // indirect
 	github.com/sigstore/rekor v1.5.3 // indirect
 	github.com/sigstore/rekor-tiles/v2 v2.3.0 // indirect
 	github.com/sigstore/sigstore v1.10.8 // indirect
 	github.com/sigstore/timestamp-authority/v2 v2.1.3 // indirect
+	github.com/stretchr/testify v1.12.1 // indirect
 	github.com/theupdateframework/go-tuf/v2 v2.4.2 // indirect
 	github.com/transparency-dev/formats v0.1.1 // indirect
 	github.com/transparency-dev/merkle v0.0.2 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
+	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 // indirect
 	github.com/yuin/goldmark-emoji v1.0.6 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
@@ -111,7 +118,9 @@ require (
 	go.opentelemetry.io/otel/trace v1.44.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.5 // indirect
 	golang.org/x/crypto v0.55.0 // indirect
+	golang.org/x/oauth2 v0.36.0 // indirect
 	golang.org/x/text v0.41.0 // indirect
+	golang.org/x/time v0.15.0 // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20260526163538-3dc84a4a5aaa // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20260523011958-0a33c5d7ca68 // indirect
 	google.golang.org/grpc v1.82.1 // indirect

go.sum

@@ -91,6 +91,8 @@ github.com/basecamp/actioncable-go v0.0.0-20260824145920-822e6cf08655 h1:zz0WUSE
 github.com/basecamp/actioncable-go v0.0.0-20260824145920-822e6cf08655/go.mod h1:ezaV5z1GXQAsqyejqTs6wCFl2D8Wj+COLQkHc/kwoRs=
 github.com/basecamp/hey-sdk/go v0.28.0 h1:N3sNaELGngFuEW9cAWner+mwhWH734Fjru/PcTdLIUg=
 github.com/basecamp/hey-sdk/go v0.28.0/go.mod h1:k6sO2XhMkU3UY8lD2ozp0735Ic3q8xoMQt7YUT3TlYk=
+github.com/basecamp/mcp v0.0.0-20260828100356-2d6f44b51e9d h1:zEQVGq1x1nhKMZ2TudFAcSJ32CHT8richI1vQakIKz4=
+github.com/basecamp/mcp v0.0.0-20260828100356-2d6f44b51e9d/go.mod h1:Ee2c/q1/pg+5T5741PIuA3s6VJMQC7I0XBNXIHIujzA=
 github.com/blang/semver v3.5.1+incompatible h1:cQNTCjp13qL8KC3Nbxr/y2Bqb63oX6wdnnjpJbkM4JQ=
 github.com/blang/semver v3.5.1+incompatible/go.mod h1:kRBLl5iJ+tD4TcOOxsy/0fnwebNt5EWlYSAyrTnjyyk=
 github.com/bmatcuk/doublestar v1.1.1/go.mod h1:UD6OnuiIn0yFxxA2le/rnRU1G4RaI4UvFv1sNto9p6w=
@@ -220,6 +222,8 @@ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/go-containerregistry v0.21.7 h1:/vPFuVXDjtFREsVArW+0h1CIl5urnOhzei4X2DMW9IU=
 github.com/google/go-containerregistry v0.21.7/go.mod h1:kjSbt7/zMsKLWfnHrIvKvhXHUw91jbe9DNjPPJ32gXE=
+github.com/google/jsonschema-go v0.4.3 h1:/DBOLZTfDow7pe2GmaJNhltueGTtDKICi8V8p+DQPd0=
+github.com/google/jsonschema-go v0.4.3/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
 github.com/google/s2a-go v0.1.9 h1:LGD7gtMgezd8a/Xak7mEWL0PjoTQFvpRudN895yqKW0=
 github.com/google/s2a-go v0.1.9/go.mod h1:YA0Ei2ZQL3acow2O62kdp9UlnvMmU7kA6Eutn0dXayM=
 github.com/google/trillian v1.7.3 h1:hziW+vo4czis48tzx2GK5xRBl/ZxBA9B0/UR5avXOro=
@@ -289,6 +293,8 @@ github.com/mitchellh/go-homedir v1.1.0 h1:lukF9ziXFxDFPkA1vsr5zpc1XuPDn/wFntq5mG
 github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
 github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
 github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
+github.com/modelcontextprotocol/go-sdk v1.7.0 h1:yqjY2dsbKAC0LSuWZVBMrHgiG8ukXv6NRo0JiALay44=
+github.com/modelcontextprotocol/go-sdk v1.7.0/go.mod h1:dL7u98E/zjJTGzEq+j30jQ8K2k1mb6LeAH4inEcSGts=
 github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA=
 github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
 github.com/natefinch/atomic v1.0.1 h1:ZPYKxkqQOx3KZ+RsbnP/YsgvxWQPGxjC0oBt2AhwV0A=
@@ -318,6 +324,10 @@ github.com/sassoftware/relic/v7 v7.6.2 h1:rS44Lbv9G9eXsukknS4mSjIAuuX+lMq/FnStgm
 github.com/sassoftware/relic/v7 v7.6.2/go.mod h1:kjmP0IBVkJZ6gXeAu35/KCEfca//+PKM6vTAsyDPY+k=
 github.com/secure-systems-lab/go-securesystemslib v0.11.0 h1:iuCR9kcMFD4QurdKrGvPLoKZLv9YvwPYVr0473BdtFs=
 github.com/secure-systems-lab/go-securesystemslib v0.11.0/go.mod h1:+PMOTjUGwHj2vcZ+TFKlb1tXRbrdWE1LYDT5i9JC80Q=
+github.com/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc=
+github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg=
+github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0=
+github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
 github.com/sergi/go-diff v1.4.0 h1:n/SP9D5ad1fORl+llWyN+D6qoUETXNZARKjyY2/KVCw=
 github.com/sergi/go-diff v1.4.0/go.mod h1:A0bzQcvG0E7Rwjx0REVgAGH58e96+X0MeOfepqsbeW4=
 github.com/shibumi/go-pathspec v1.3.0 h1:QUyMZhFo0Md5B8zV8x2tesohbb5kfbpTi9rBnKh5dkI=
@@ -349,8 +359,8 @@ github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
 github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/spkg/bom v0.0.0-20160624110644-59b7046e48ad/go.mod h1:qLr4V1qq6nMqFKkMo8ZTx3f+BZEkzsRUY10Xsm2mwU0=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
-github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/objx v0.5.3 h1:jmXUvGomnU1o3W/V5h2VEradbpJDwGrzugQQvL0POH4=
+github.com/stretchr/objx v0.5.3/go.mod h1:rDQraq+vQZU7Fde9LOZLr8Tax6zZvy4kuNKF+QYS+U0=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
 github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
@@ -374,6 +384,8 @@ github.com/transparency-dev/merkle v0.0.2 h1:Q9nBoQcZcgPamMkGn7ghV8XiTZ/kRxn1yCG
 github.com/transparency-dev/merkle v0.0.2/go.mod h1:pqSy+OXefQ1EDUVmAJ8MUhHB9TXGuzVAT58PqBoHz1A=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
+github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
+github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 h1:ilQV1hzziu+LLM3zUTJ0trRztfwgjqKnBWNtSRkbmwM=
 github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78/go.mod h1:aL8wCCfTfSfmXjznFBSZNN13rSJjlIOI1fUNAtF7rmI=
 github.com/yuin/goldmark v1.8.5 h1:r6N5afV5qj/5S4UTch8agZHJ8UxNCMwX7WjkkJam2NA=
@@ -431,6 +443,8 @@ golang.org/x/text v0.41.0 h1:vz/seA0lnX87Othu2f/0L24RcgrXD9/YFTSuGjj3rH8=
 golang.org/x/text v0.41.0/go.mod h1:jvf1O8ajNzZqhSrQBPbutR/EB83Cc0CFrezNQIwbb5M=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
+golang.org/x/tools v0.49.0 h1:3NI7VXzL9+1WZD52Dx2ttoPwD5DWrFGpl9mFZDlmisI=
+golang.org/x/tools v0.49.0/go.mod h1:SJNXV9DBKT0UbdttsQjbfJlAE/q+y36++zo3uL3N0Oo=
 gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
 gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
 google.golang.org/api v0.283.0 h1:0lkp8u0MPwJVHqRL+nJlMAoZVVzbmiXmFHXMOTmSPik=

internal/cmd/help.go

@@ -41,7 +41,7 @@ var curatedCategories = []struct {
 	},
 	{
 		heading: "ACCOUNT & SYSTEM",
-		names:   []string{"auth", "account", "config", "setup", "shell-completion", "doctor", "upgrade", "version"},
+		names:   []string{"auth", "account", "config", "setup", "mcp", "shell-completion", "doctor", "upgrade", "version"},
 	},
 }
 

internal/cmd/help_test.go

@@ -155,6 +155,7 @@ ACCOUNT & SYSTEM
   account           List and select linked mail accounts
   config            View and change settings
   setup             Set up HEY for first use
+  mcp               Serve HEY to MCP clients over stdio
   shell-completion  Set up tab completion for your shell
   doctor            Find login and configuration problems
   upgrade           Upgrade hey to the latest release

internal/cmd/mcp.go

@@ -0,0 +1,110 @@
+package cmd
+
+import (
+	"context"
+	"log/slog"
+	"os"
+	"os/signal"
+	"syscall"
+
+	hey "github.com/basecamp/hey-sdk/go/pkg/hey"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/spf13/cobra"
+
+	"github.com/basecamp/hey-cli/internal/mcpserver"
+)
+
+// mcpTransport is a seam so tests can drive the server over in-memory
+// transports instead of the process's stdin/stdout.
+var mcpTransport = func() mcp.Transport { return &mcp.StdioTransport{} }
+
+type mcpCommand struct {
+	cmd      *cobra.Command
+	readOnly bool
+	domains  []string
+}
+
+func newMCPCommand() *mcpCommand {
+	mcpCommand := &mcpCommand{}
+	mcpCommand.cmd = &cobra.Command{
+		Use:   "mcp",
+		Short: "Serve HEY to MCP clients over stdio",
+		Long: "Run an MCP (Model Context Protocol) server on stdin/stdout, serving HEY mail,\n" +
+			"contacts, and todos as tools backed by your signed-in account.\n\n" +
+			"Register it with an MCP client as a stdio server, e.g.:\n\n" +
+			"  claude mcp add hey -- hey mcp",
+		Args: cobra.NoArgs,
+		Annotations: map[string]string{
+			"agent_notes": "Long-running server; stdout speaks the MCP wire protocol. Not for interactive use.",
+		},
+		RunE: mcpCommand.run,
+	}
+
+	mcpCommand.cmd.Flags().BoolVar(&mcpCommand.readOnly, "read-only", false, "Serve only read-only actions")
+	mcpCommand.cmd.Flags().StringSliceVar(&mcpCommand.domains, "domains", nil, "Narrow to specific domains (comma-separated; default all)")
+
+	return mcpCommand
+}
+
+// mcpAPI is the dispatcher's view of the SDK, split by verb: reads ride the
+// shared client's retry policy, while mutations go through a twin that never
+// retries on 429/503. UpdateMessage delivers mail on PUT, and its contract
+// forbids a transparent retry after an ambiguous first attempt — a duplicate
+// send is irreversible. POST and PATCH never auto-retried, so sending PUT and
+// DELETE through the no-retry twin makes every mutation single-shot. A 401
+// still refreshes the token before the error surfaces, so a caller's own
+// retry goes out with fresh credentials.
+type mcpAPI struct {
+	reads, writes *hey.Client
+}
+
+func (a mcpAPI) Get(ctx context.Context, path string) (*hey.Response, error) {
+	return a.reads.Get(ctx, path)
+}
+
+func (a mcpAPI) Post(ctx context.Context, path string, body any) (*hey.Response, error) {
+	return a.writes.Post(ctx, path, body)
+}
+
+func (a mcpAPI) Put(ctx context.Context, path string, body any) (*hey.Response, error) {
+	return a.writes.Put(ctx, path, body)
+}
+
+func (a mcpAPI) Patch(ctx context.Context, path string, body any) (*hey.Response, error) {
+	return a.writes.Patch(ctx, path, body)
+}
+
+func (a mcpAPI) Delete(ctx context.Context, path string) (*hey.Response, error) {
+	return a.writes.Delete(ctx, path)
+}
+
+func (c *mcpCommand) run(cmd *cobra.Command, args []string) error {
+	if err := requireAuth(); err != nil {
+		return err
+	}
+
+	// The same account scoping the shared client got in the root command's
+	// pre-run, applied to the no-retry twin.
+	writes, err := clientForAccountSelection(cmd.Context(), newSDKClient(hey.WithMaxRetries(0)), cfg.AccountID)
+	if err != nil {
+		return err
+	}
+
+	srv, err := mcpserver.New(mcpAPI{reads: sdk, writes: writes}, mcpserver.Config{ReadOnly: c.readOnly, Domains: c.domains})
+	if err != nil {
+		return err
+	}
+
+	ctx, stop := signal.NotifyContext(cmd.Context(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+
+	// Log to stderr: stdout belongs to the MCP wire.
+	logger := slog.New(slog.NewTextHandler(cmd.ErrOrStderr(), nil))
+	session, err := srv.BuildMCPServer(logger).Connect(ctx, mcpTransport(), nil)
+	if err != nil {
+		return err
+	}
+	logger.Info("MCP server running on stdio", "tools", len(srv.Domains()), "read_only", c.readOnly)
+
+	return session.Wait()
+}