Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

onboarding: make Beacon Cloud MCP the opt-out MCP step, for Beacon Cloud only

Claude64fc5ceaf581
diff --git a/CLAUDE.md b/CLAUDE.md
index 9ccd7352..88277b3e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -28,7 +28,7 @@ Do not recreate or depend on removed `asymptote` mirror trees. Keep new work foc
- Preserve the local-only default. The public Beacon build must not require a hosted account, remote policy fetch, hosted dashboard, or external network dependency during normal hook execution, and hooks themselves never touch the network.
- `beacon login` is the account-identity channel for interactive users and is required by the interactive `beacon endpoint install` wizard. It uses browser PKCE against beacon.sh and stores the scoped CLI token only in `~/.beacon/auth/session.json` (0600 under a 0700 directory). Signing in alone never starts forwarding. User-mode `beacon endpoint connect` may send that token once to `POST /api/cli/enroll/account` to authorize minting a separate device ingest key, and `beacon mcp token create` may send it to `POST /api/cli/mcp/tokens` (scope `mcp:token:create`, listed on the sign-in page) to mint a personal MCP token that is printed once to stdout and never written to a file; never copy the account token into endpoint config, Vector, hook environments, logs, or command output. System/root/package/MDM/CI/piped-stdin/dry-run installs stay noninteractive and account-free.
- Beacon Cloud forwarding (`cli/beacon/internal/endpoint/asymptote`, `beacon endpoint connect`, `beacon endpoint asymptote`) is Vector-shaped: Beacon writes local JSONL, Vector ships runtime lines only from the connection point forward and reads inventory from the beginning to establish the endpoint's current baseline, and the `bcn_device_*` key stays only in `<BaseDir>/asymptote/vector-secrets.json` via Vector's secret backend. The onboarding wizard preselects Beacon Cloud, and confirming it connects this endpoint in the same command once the local install has succeeded; an endpoint that is already enrolled is never re-enrolled, because enrollment rotates the device key. Standard mode ships locally sanitized retained content; metadata-only uses local Vector transforms to remove prompts, responses, reasoning, tool arguments/results, command output, raw fields, diffs, inventory content, and MCP definitions before buffering/upload. Keep the ingest URL `https://`, the wire contract aligned with `beacon-ingest` (`/v1/ingest/{runtime,inventory}` and `/v1/ingest/health`), and do not add another endpoint network channel. The cloud-sandbox shuttle is the bounded exception: only with `BEACON_ORIGIN=cloud`, it can upload new runtime lines to GCS, S3, or the same Beacon ingest contract because no Vector/service manager/browser/persistent disk exists there.
-- `beacon endpoint install` has a full-screen onboarding wizard on interactive user TTYs. It signs in, preselects Beacon Cloud, requires an explicit choice to opt out to Local, and asks Managed users to choose Standard or Metadata-only privacy. Signing in alone still moves no telemetry. Confirming Beacon Cloud does: the confirm screen states that it installs Beacon and starts forwarding, and names what the selected privacy mode sends, so that screen is the consent point. The managed destination is recorded only after enrollment succeeds, so a failed enrollment leaves a working local install, prints `beacon endpoint connect` as the retry, and re-offers the question on the next install. The onboarding record is written only after `lifecycle.Install` returns, because a profile written first left a failed install looking onboarded and silently skipped the wizard on the retry. Explicit `install --connect` is unchanged. The wizard is skipped for system/root/CI/piped-stdin/dry-run or `BEACON_ONBOARDING=0`; those unattended paths must never gain an account or browser dependency. Legacy `BEACON_ONBOARDING_EMAIL`/`USAGE` submissions remain only for fleet compatibility. After the destination, the wizard offers two agent tools for either destination, both preselected (opt-out, space toggles): the local `beacon` stdio MCP server registered in detected harnesses (`mcpconnect.InstallLocal`, `beacon mcp install|uninstall`, manifest `~/.beacon/mcp/local.json`; it adds the entry only where the name `beacon` is free and never replaces one) and the Beacon Agent Skills installed user-wide into `~/.agents/skills` and, when Claude Code is set up, `~/.claude/skills` (`cli/beacon/internal/agentskills`, `beacon skills install|uninstall`; a `.beacon-managed` marker decides what Beacon may replace or remove). Both run after `lifecycle.Install` returns, warn rather than fail, and never touch the network; install and repair refresh only skill copies Beacon already wrote. The answers are recorded as `onboarding.mcp_server`/`agent_skills`. Implementation lives in `cli/beacon/internal/onboarding`, `cli/beacon/cmd/endpoint_onboarding.go` and `cli/beacon/cmd/agent_tools.go`; keep `docs/cli/endpoint-onboarding.mdx`, `docs/cli/mcp-install.mdx` and `docs/cli/skills.mdx` in sync.
+- `beacon endpoint install` has a full-screen onboarding wizard on interactive user TTYs. It signs in, preselects Beacon Cloud, requires an explicit choice to opt out to Local, and asks Managed users to choose Standard or Metadata-only privacy. Signing in alone still moves no telemetry. Confirming Beacon Cloud does: the confirm screen states that it installs Beacon and starts forwarding, and names what the selected privacy mode sends, so that screen is the consent point. The managed destination is recorded only after enrollment succeeds, so a failed enrollment leaves a working local install, prints `beacon endpoint connect` as the retry, and re-offers the question on the next install. The onboarding record is written only after `lifecycle.Install` returns, because a profile written first left a failed install looking onboarded and silently skipped the wizard on the retry. Explicit `install --connect` is unchanged. The wizard is skipped for system/root/CI/piped-stdin/dry-run or `BEACON_ONBOARDING=0`; those unattended paths must never gain an account or browser dependency. Legacy `BEACON_ONBOARDING_EMAIL`/`USAGE` submissions remain only for fleet compatibility. After the destination, the wizard shows an agent tools screen; every row is preselected (opt-out, space toggles). Beacon Cloud MCP is offered only with Beacon Cloud and runs the `beacon mcp connect` flow (`connectCloudMCP` with `yes`, OAuth, detected harnesses) only after the endpoint is connected (or already was), via `finishCloudSetup`; a failed enrollment skips it and names the retry. The Beacon Agent Skills are offered for either destination and installed user-wide into `~/.agents/skills` and, when Claude Code is set up, `~/.claude/skills` (`cli/beacon/internal/agentskills`, `beacon skills install|uninstall`; a `.beacon-managed` marker decides what Beacon may replace or remove; install and repair refresh only copies Beacon already wrote). Both run after `lifecycle.Install` returns and warn rather than fail. The answers are recorded as `onboarding.cloud_mcp`/`agent_skills`. Implementation lives in `cli/beacon/internal/onboarding`, `cli/beacon/cmd/endpoint_onboarding.go`, `cli/beacon/cmd/endpoint_install.go` and `cli/beacon/cmd/agent_tools.go`; keep `docs/cli/endpoint-onboarding.mdx` and `docs/cli/skills.mdx` in sync.
- Do not add dependency vulnerability scanning, OSV/GHSA lookups, package remediation, or other vulnerability-enforcement flows to the public hook path.
- Do not add broad runtime enforcement unless explicitly requested. Current control behavior is limited to hook-native approvals/denials exposed by supported agent runtimes.
- Keep destination support shaped like the existing local JSONL and customer-managed forwarding paths. Beacon may render supported packs or token-based endpoint forwarders, but should not add hosted SIEM dependencies or store third-party service credentials beyond the explicit supported configs. Elastic remains a file-tailing pack over local JSONL.
@@ -68,7 +68,7 @@ Supported runtime surfaces today:
- Local threat detection via `beacon scan`, which runs the open Threat Rules format (`spec/threat-rules`; CEL match conditions over the endpoint event schema, with embedded conformance fixtures) over the runtime JSONL. The engine (`pkg/asymptoteobserve/threatrules`) ships in the binary; the rule corpus is external data loaded from a local store (`~/.beacon/endpoint/rules`) managed by `beacon rules`, so the corpus can grow without enlarging the binary. `scan` is read-only and offline; only the explicit, user-initiated `beacon rules pull <url>` reaches the network. A small frozen baseline is embedded so `scan` works before any rules are installed.
- Session handoff via `beacon handoff list|export|resume` (`cli/beacon/internal/handoff`, `cli/beacon/cmd/handoff*.go`; docs in `docs/cli/handoff.mdx` and `docs/concepts/session-handoff.mdx`). Every runtime is one entry in the registry in `cli/beacon/internal/handoff/runtimes.go`: its session source, the names it answers to, and the commands that reopen it or start it from a brief; `TestRegistryIsConsistent` checks the entries. Handoff reads the session stores of Claude Code, Codex CLI, OpenCode, Cline, Pi, Prime Agent, Factory Droid, GitHub Copilot CLI, Hermes Agent, DeepSeek Harness, fx, Grok Build, OpenClaw Gateway and Cursor read-only and never touches the network. Oh My Pi, Gemini CLI, Qwen Code, Kiro, Antigravity CLI, Devin CLI, Muse Code, OpenHands and goose have no store Beacon reads: their sessions come from the runtime log, and they take a brief as the target of `--agent`. `resume` reopens a session natively with its runtime's own command when it can, and otherwise writes a brief to `~/.beacon/endpoint/handoffs` (0700/0600) and starts a new session pointed at it. DeepSeek Harness cannot be started, and Hermes Agent and fx only reopen their own sessions, so their sessions continue in another runtime. fx, Grok Build and Cursor find a session by the directory they run in, so they are reopened natively only in the session's own directory. The brief is passed by absolute path, never inlined on a command line. Every launch keeps the runtime's approvals on: Beacon never passes a flag that turns them off, names the approval mode that asks where a CLI takes one (Cline always gets `--auto-approve false`, because Cline defaults to approving every tool call), and removes or overrides environment switches that would approve everything (`COPILOT_ALLOW_ALL`, `COPILOT_PLAN_THEN_AUTOPILOT`, `HERMES_YOLO_MODE`, `GOOSE_MODE`); `--print` shows them under `env`. Briefs run every event through `SanitizeEvent`, and quoted content goes in fences longer than any backtick run it contains, with inline fields reduced to one line, so quoted content cannot forge brief structure. A new session's first prompt ends with the `[beacon-handoff from=<harness> session=<id>]` marker (`pkg/asymptoteobserve/handoff.go`). The hook and plugin prompt paths and the session-store mappers record a `session.handoff` event with `handoff.{source_harness,source_session_id}` when they see it; that is an observed claim, not a verified identity.
- Commit-to-session links via `beacon git setup|status|remove|link|notes` (`cli/beacon/internal/gitlink`, `cli/beacon/cmd/git*.go`; docs in `docs/cli/git.mdx`). A link is a `beacon:<harness>/<session-id>` line in a git note under `refs/notes/beacon`; it carries identifiers only, never content, because notes can be pushed. Which sessions to link is inferred from the local runtime log: a session is linked when, between the parent commit and the commit (at least two hours, at most 24), it wrote a file the commit changes (for a merge, only files that differ from every parent, so a clean merge or pull links nothing). Evidence is file write events, write-type `file.operation`s, plainly readable shell targets, and `apply_patch` envelopes; reads never count. Note updates are a compare-and-swap on the notes ref through a private `refs/notes/beacon-tx/` working ref, and every existing note line, a teammate's or a person's, is kept verbatim. `setup` installs post-commit (links HEAD in the foreground with a 3 s budget, silent, never fails the commit, skips rebase/cherry-pick/revert) and post-rewrite (normalizes the note git concatenates on amend) as standalone `beacon-<hook>` scripts called from a marked block inserted after the shebang of the repository's own hook; only shell hooks are edited, `core.hooksPath` is refused without `--hooks-path`, and `notes.rewriteRef` carries links through amend and rebase. `BEACON_GIT_HOOKS=0` disables the hooks for one command. Every link a run adds is also written to the runtime log as one `session.commit_linked` event in the linked session's timeline (`event.fidelity=inferred`, no collection method), with commit id, branch and credential-stripped remote in the OTel-shaped `vcs` block and overlap counts in `vcs.attribution`; the event deliberately carries no file, command or tool fields so it can never become attribution evidence. Sharing is opt-in (`setup --share-notes`, off by default): a non-destructive fetch refspec `+refs/notes/beacon:refs/notes/beacon-remotes/<remote>` so git's own fetch brings teammates' links into a read-only tracking ref that `beacon git notes` unions with the local one (never force-fetch into `refs/notes/beacon`: it would destroy unpushed links), and a pre-push hook that fetches, merges with `cat_sort_uniq` through the same CAS, and pushes only the notes ref with `--no-verify`, within a 10 s budget and never failing the push. That pre-push hook is the only Beacon git hook that touches the network, and only during a push the person started; `beacon git notes push|fetch` do the same by hand.
-- Beacon Cloud MCP registration via `beacon mcp connect|disconnect|status` (`cli/beacon/internal/mcpconnect`, `cli/beacon/cmd/mcp_connect.go`; docs in `docs/cli/mcp-connect.mdx`). It registers the Beacon Cloud MCP server as `beacon-managed`, a different name from the local stdio server `beacon`, in the user-level config of Claude Code, Codex CLI, Cursor, VS Code, Gemini CLI and OpenCode. It prints manual steps for runtimes without confirmed MCP OAuth support. OAuth is the default and writes only the URL; `--token-env` writes a reference to an environment variable in each harness's own syntax, never a value. `connect` never reads or copies the account token and never writes a token; minting one is the separate, explicit `beacon mcp token create`. It is explicit and interactive: never run by `endpoint install` or onboarding (the install only suggests it after the wizard's Managed choice; what onboarding registers is the separate local `beacon` server), refused as root, and refused in CI or without a terminal unless `--yes` is given. Its one network request is the RFC 9728 resource-metadata check of the URL, which `--dry-run` skips. Configs are edited like the Kimi Code writer: never re-serialized, spliced as text, parsed back and compared before an atomic replace, backed up first. What was written is recorded in `~/.beacon/mcp/connections.json`, and `disconnect` removes only entries recorded there that still point at the recorded URL. `cmd/mcp_connect_e2e_test.go` runs the real harness CLIs when they are installed; re-run it when a harness changes its MCP config format.
+- Beacon Cloud MCP registration via `beacon mcp connect|disconnect|status` (`cli/beacon/internal/mcpconnect`, `cli/beacon/cmd/mcp_connect.go`; docs in `docs/cli/mcp-connect.mdx`). It registers the Beacon Cloud MCP server as `beacon-managed`, a different name from the local stdio server `beacon`, in the user-level config of Claude Code, Codex CLI, Cursor, VS Code, Gemini CLI and OpenCode. It prints manual steps for runtimes without confirmed MCP OAuth support. OAuth is the default and writes only the URL; `--token-env` writes a reference to an environment variable in each harness's own syntax, never a value. `connect` never reads or copies the account token and never writes a token; minting one is the separate, explicit `beacon mcp token create`. It is explicit and interactive: never run by an unattended install; the onboarding wizard runs it only after the person chose Beacon Cloud and left "Beacon Cloud MCP" selected (that screen is the confirmation), and otherwise the install only suggests it. It is refused as root, and refused in CI or without a terminal unless `--yes` is given. Its one network request is the RFC 9728 resource-metadata check of the URL, which `--dry-run` skips. Configs are edited like the Kimi Code writer: never re-serialized, spliced as text, parsed back and compared before an atomic replace, backed up first. What was written is recorded in `~/.beacon/mcp/connections.json`, and `disconnect` removes only entries recorded there that still point at the recorded URL. `cmd/mcp_connect_e2e_test.go` runs the real harness CLIs when they are installed; re-run it when a harness changes its MCP config format.
- An optional, off-by-default policy seam in the hook path (`cli/beacon-hooks/internal/policy`) governed by the stable contract in `pkg/asymptoteobserve/policycontract`. When `BEACON_POLICY_PROVIDER` names an executable, the `pre-tool` and `permission-request` hooks send it a JSON request describing the imminent tool call and honor an allow/deny response, returning the runtime's native deny shape and `policy.enforcement=enforce` telemetry on a deny. The seam is inert when unset and fail-open on any error (timeout, non-zero exit, malformed output), so the open build ships no enforcement of its own; all audit/enforce decision logic lives in the external provider. `rules/agent-control/agent-permission-bypass-spawn.rule.yaml` is the open detect twin that flags the same pattern in `beacon scan`.
Current non-goals unless explicitly requested:
diff --git a/README.md b/README.md
index 202d57cd..81d979bb 100644
--- a/README.md
+++ b/README.md
@@ -154,13 +154,14 @@ Or inspect the raw event stream:
> Local to keep everything on this machine, and disconnect any time with
> `beacon endpoint disconnect`.
-Whichever destination you choose, the wizard also sets up two agent tools unless you
-turn them off: the local `beacon` MCP server (`beacon mcp serve`) in every detected
-harness, and the [Beacon Skills](https://docs.beacon.sh/concepts/beacon-skills) in
-`~/.agents/skills` and `~/.claude/skills`. Both read local data only. Redo or undo
-them with `beacon mcp install|uninstall` and `beacon skills install|uninstall`.
-
-If this endpoint forwards to Beacon Cloud, your agents can search that history over MCP:
+Whichever destination you choose, the wizard also installs the
+[Beacon Skills](https://docs.beacon.sh/concepts/beacon-skills) into `~/.agents/skills`
+and `~/.claude/skills` unless you turn them off; redo or undo that with
+`beacon skills install|uninstall`.
+
+If you choose Beacon Cloud, the wizard also registers Beacon Cloud MCP in your harnesses
+unless you turn it off, so your agents can search the forwarded history. To do it later,
+or for an endpoint connected another way:
```bash
beacon mcp connect
diff --git a/cli/beacon/cmd/agent_tools.go b/cli/beacon/cmd/agent_tools.go
index 20e7963b..38b973fd 100644
--- a/cli/beacon/cmd/agent_tools.go
+++ b/cli/beacon/cmd/agent_tools.go
@@ -7,37 +7,20 @@ import (
"github.com/spf13/cobra"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/agentskills"
- "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/mcpconnect"
)
-// Agent tools are what onboarding sets up for the person's agents, whichever destination they
-// chose: the local Beacon MCP server registered in each detected harness, and the Beacon Agent
-// Skills installed user-wide. Both are selected by default in the wizard and turned off there;
-// `beacon mcp install|uninstall` and `beacon skills install|uninstall` redo or undo them later.
-// Neither touches the network.
+// Agent tools are what onboarding sets up for the person's agents once the install succeeds:
+// Beacon Cloud MCP, offered only when Beacon Cloud was chosen, and the Beacon Agent Skills,
+// offered whichever destination was chosen. Both start selected in the wizard and are turned
+// off there. `beacon mcp connect|disconnect` and `beacon skills install|uninstall` redo or
+// undo them later. Installing the skills never touches the network.
// Seams for tests.
var (
- agentToolsHome = mcpHome
- agentToolsExecutable = beaconExecutable
+ agentToolsHome = mcpHome
+ agentToolsConnectCloudMCP = connectCloudMCP
)
-var mcpInstallCmd = &cobra.Command{
- Use: "install",
- Short: "Register the local Beacon MCP server in detected harnesses",
- SilenceUsage: true,
- RunE: func(cmd *cobra.Command, args []string) error {
- return installLocalMCP(cmd.OutOrStdout(), cmd)
- },
-}
-
-var mcpUninstallCmd = &cobra.Command{
- Use: "uninstall",
- Short: "Remove the local Beacon MCP server entries Beacon registered",
- SilenceUsage: true,
- RunE: runMCPUninstall,
-}
-
var skillsCmd = &cobra.Command{
Use: "skills",
Short: "Install the Beacon Agent Skills for every project",
@@ -65,114 +48,34 @@ var skillsUninstallCmd = &cobra.Command{
}
func init() {
- mcpCmd.AddCommand(mcpInstallCmd, mcpUninstallCmd)
- mcpInstallCmd.Flags().StringSliceVar(&mcpConnectOpts.harnesses, "harness", nil, "Harness to configure (repeatable; default: every detected harness)")
rootCmd.AddCommand(skillsCmd)
skillsCmd.AddCommand(skillsInstallCmd, skillsUninstallCmd)
- mcpInstallCmd.PreRunE = refuseRoot("beacon mcp install")
- mcpUninstallCmd.PreRunE = refuseRoot("beacon mcp uninstall")
skillsInstallCmd.PreRunE = refuseRoot("beacon skills install")
skillsUninstallCmd.PreRunE = refuseRoot("beacon skills uninstall")
}
-func localMCPOptions(home string) mcpconnect.LocalOptions {
- return mcpconnect.LocalOptions{Home: home, Command: agentToolsExecutable(), LookPath: mcpLookPath, Run: mcpRunCLI}
-}
-
-// installAgentTools carries out the agent tools the wizard kept selected. It runs after the local
-// install has succeeded, and a failure is a warning: the endpoint works without them.
-func installAgentTools(cmd *cobra.Command, decided onboardingOutcome) {
- if !decided.InstallMCP && !decided.InstallSkills {
+// installAgentSkillsFromOnboarding installs the skills the wizard kept selected. It runs after
+// the local install has succeeded, and a failure is a warning: the endpoint works without them.
+func installAgentSkillsFromOnboarding(cmd *cobra.Command, decided onboardingOutcome) {
+ if !decided.InstallSkills {
return
}
- out := cmd.OutOrStdout()
- if decided.InstallMCP {
- if err := installLocalMCP(out, cmd); err != nil {
- fmt.Fprintf(cmd.ErrOrStderr(), "beacon: the Beacon MCP server was not registered (%v). Run `beacon mcp install` to try again.\n", err)
- }
- }
- if decided.InstallSkills {
- if err := installAgentSkills(out); err != nil {
- fmt.Fprintf(cmd.ErrOrStderr(), "beacon: the Beacon agent skills were not installed (%v). Run `beacon skills install` to try again.\n", err)
- }
- }
-}
-
-func installLocalMCP(out io.Writer, cmd *cobra.Command) error {
- home, err := agentToolsHome()
- if err != nil {
- return err
- }
- targets, _, err := resolveMCPTargets(mcpConnectOpts.harnesses)
- if err != nil {
- return err
- }
- var local []mcpconnect.Target
- for _, t := range targets {
- if t.LocalSupported() {
- local = append(local, t)
- }
- }
- if len(local) == 0 {
- fmt.Fprintln(out, "Beacon MCP server: no harness Beacon can register it in was detected.")
- return nil
- }
- items, err := mcpconnect.InstallLocal(commandContext(cmd), localMCPOptions(home), local)
- if err != nil {
- return err
- }
- var failed int
- for _, it := range items {
- where := displayPath(home, it.Path)
- switch {
- case it.Err != nil:
- failed++
- fmt.Fprintf(out, "Beacon MCP server: %s not registered: %v\n", it.Target.DisplayName, it.Err)
- case it.Action == mcpconnect.ActionAdd:
- fmt.Fprintf(out, "Beacon MCP server: registered for %s (%s)\n", it.Target.DisplayName, where)
- case it.Action == mcpconnect.ActionPresent:
- fmt.Fprintf(out, "Beacon MCP server: %s already has a %q entry; left as is\n", it.Target.DisplayName, mcpconnect.LocalServerName)
- default:
- fmt.Fprintf(out, "Beacon MCP server: %s skipped: %s\n", it.Target.DisplayName, it.Detail)
- }
- }
- if failed > 0 {
- return fmt.Errorf("%d harness(es) could not be configured", failed)
+ if err := installAgentSkills(cmd.OutOrStdout()); err != nil {
+ fmt.Fprintf(cmd.ErrOrStderr(), "beacon: the Beacon agent skills were not installed (%v). Run `beacon skills install` to try again.\n", err)
}
- return nil
}
-func runMCPUninstall(cmd *cobra.Command, args []string) error {
- out := cmd.OutOrStdout()
- home, err := agentToolsHome()
+// connectCloudMCPFromOnboarding registers Beacon Cloud MCP in the detected harnesses, as
+// `beacon mcp connect --yes` would, once this endpoint forwards to Beacon Cloud. Leaving the
+// row selected on the wizard's agent tools screen is the confirmation connect would otherwise
+// ask for. It writes only the URL (each harness signs in with OAuth on first use) and never a
+// token. A failure is a warning naming the retry.
+func connectCloudMCPFromOnboarding(cmd *cobra.Command) {
+ fmt.Fprintln(cmd.OutOrStdout())
+ err := agentToolsConnectCloudMCP(commandContext(cmd), cmd.OutOrStdout(), cloudMCPRequest{yes: true})
if err != nil {
- return err
- }
- items, err := mcpconnect.UninstallLocal(commandContext(cmd), localMCPOptions(home))
- if err != nil {
- return err
- }
- if len(items) == 0 {
- fmt.Fprintln(out, "No local Beacon MCP server entries written by Beacon.")
- return nil
- }
- var failed int
- for _, it := range items {
- where := displayPath(home, it.Path)
- switch {
- case it.Err != nil:
- failed++
- fmt.Fprintf(out, "%s: %v\n", it.Target.DisplayName, it.Err)
- case it.Action == mcpconnect.ActionRemove:
- fmt.Fprintf(out, "Removed from %s (%s)\n", it.Target.DisplayName, where)
- default:
- fmt.Fprintf(out, "%s: %s\n", it.Target.DisplayName, it.Detail)
- }
+ fmt.Fprintf(cmd.ErrOrStderr(), "beacon: Beacon Cloud MCP was not registered (%v). Run `beacon mcp connect` to try again.\n", err)
}
- if failed > 0 {
- return fmt.Errorf("%d entr(ies) could not be removed", failed)
- }
- return nil
}
func installAgentSkills(out io.Writer) error {
diff --git a/cli/beacon/cmd/agent_tools_test.go b/cli/beacon/cmd/agent_tools_test.go
index 3d79153c..709bee70 100644
--- a/cli/beacon/cmd/agent_tools_test.go
+++ b/cli/beacon/cmd/agent_tools_test.go
@@ -13,32 +13,35 @@ import (
"github.com/spf13/cobra"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/agentskills"
- "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/harness"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/onboarding"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
)
-func TestOnboardingOffersAgentToolsWhicheverDestination(t *testing.T) {
+func TestOnboardingAgentToolsOutcomeAndRecord(t *testing.T) {
for _, tc := range []struct {
+ name string
destination string
- mcp, skills bool
+ cloudMCP bool
+ skills bool
+ wantCloudMCP bool
wantMCPAnswer string
wantSkills string
}{
- {onboarding.DestinationLocal, true, true, onboarding.AgentToolInstalled, onboarding.AgentToolInstalled},
- {onboarding.DestinationAsymptote, true, false, onboarding.AgentToolInstalled, onboarding.AgentToolDeclined},
- {onboarding.DestinationLocal, false, false, onboarding.AgentToolDeclined, onboarding.AgentToolDeclined},
+ {"cloud keeps both", onboarding.DestinationAsymptote, true, true, true, onboarding.AgentToolInstalled, onboarding.AgentToolInstalled},
+ {"cloud declines MCP", onboarding.DestinationAsymptote, false, true, false, onboarding.AgentToolDeclined, onboarding.AgentToolInstalled},
+ // Local is never asked about Beacon Cloud MCP, so nothing is acted on or recorded for it.
+ {"local", onboarding.DestinationLocal, true, false, false, "", onboarding.AgentToolDeclined},
} {
h := newOnboardingHarness(t)
var offered bool
onboardingRunWizard = func(_ io.Reader, _ io.Writer, opts onboarding.WizardOptions) (onboarding.WizardResult, error) {
offered = opts.OfferAgentTools
return onboarding.WizardResult{
- Completed: true,
- Destination: tc.destination,
- PrivacyMode: "standard",
- InstallMCP: tc.mcp,
- InstallSkills: tc.skills,
+ Completed: true,
+ Destination: tc.destination,
+ PrivacyMode: "standard",
+ ConnectCloudMCP: tc.cloudMCP,
+ InstallSkills: tc.skills,
}, nil
}
outcome, err := maybeRunOnboarding(h.cmd)
@@ -46,151 +49,207 @@ func TestOnboardingOffersAgentToolsWhicheverDestination(t *testing.T) {
t.Fatal(err)
}
if !offered {
- t.Fatalf("%s: the wizard was not offered the agent tools", tc.destination)
+ t.Fatalf("%s: the wizard was not offered the agent tools", tc.name)
}
- if outcome.InstallMCP != tc.mcp || outcome.InstallSkills != tc.skills {
- t.Fatalf("%s: outcome = %+v", tc.destination, outcome)
+ if outcome.ConnectCloudMCP != tc.wantCloudMCP || outcome.InstallSkills != tc.skills {
+ t.Fatalf("%s: outcome = %+v", tc.name, outcome)
}
if err := outcome.Persist(); err != nil {
t.Fatal(err)
}
got := h.saved[len(h.saved)-1].Onboarding
- if got.MCPServer != tc.wantMCPAnswer || got.AgentSkills != tc.wantSkills {
- t.Fatalf("%s: recorded mcp=%q skills=%q", tc.destination, got.MCPServer, got.AgentSkills)
+ if got.CloudMCP != tc.wantMCPAnswer || got.AgentSkills != tc.wantSkills {
+ t.Fatalf("%s: recorded cloud_mcp=%q agent_skills=%q", tc.name, got.CloudMCP, got.AgentSkills)
}
}
}
-type agentToolsFixture struct {
- home string
- cmd *cobra.Command
- out *bytes.Buffer
- err *bytes.Buffer
+func agentToolsCommand(t *testing.T) (*cobra.Command, *bytes.Buffer, *bytes.Buffer) {
+ t.Helper()
+ cmd := &cobra.Command{}
+ var out, errOut bytes.Buffer
+ cmd.SetOut(&out)
+ cmd.SetErr(&errOut)
+ cmd.SetContext(context.Background())
+ return cmd, &out, &errOut
+}
+
+// Onboarding registers Beacon Cloud MCP through the same flow as `beacon mcp connect --yes`:
+// detected harnesses, OAuth (only the URL is written), and no question on stdin.
+func TestOnboardingRegistersCloudMCPWithoutAsking(t *testing.T) {
+ fx := newMCPFixture(t, "cursor")
+ mcpIngestURL = func() string { return strings.TrimSuffix(fx.url, "/mcp") }
+ mcpStdin = strings.NewReader("n\n") // would decline if it were asked
+ cmd, out, errOut := agentToolsCommand(t)
+
+ connectCloudMCPFromOnboarding(cmd)
+
+ if errOut.Len() != 0 {
+ t.Fatalf("stderr: %s\nstdout: %s", errOut, out)
+ }
+ data, err := os.ReadFile(filepath.Join(fx.home, ".cursor", "mcp.json"))
+ if err != nil {
+ t.Fatalf("cursor config not written: %v\n%s", err, out)
+ }
+ if !strings.Contains(string(data), `"beacon-managed"`) || !strings.Contains(string(data), fx.url) {
+ t.Fatalf("cursor config:\n%s", data)
+ }
+ if strings.Contains(string(data), fakeAccountToken) || strings.Contains(out.String(), fakeAccountToken) {
+ t.Fatal("the account token leaked")
+ }
+ if strings.Contains(out.String(), "[y/N]") {
+ t.Fatalf("onboarding asked again:\n%s", out)
+ }
}
-func newAgentToolsFixture(t *testing.T) agentToolsFixture {
+func TestOnboardingCloudMCPFailureIsAWarning(t *testing.T) {
+ prev := agentToolsConnectCloudMCP
+ t.Cleanup(func() { agentToolsConnectCloudMCP = prev })
+ var got cloudMCPRequest
+ agentToolsConnectCloudMCP = func(_ context.Context, _ io.Writer, req cloudMCPRequest) error {
+ got = req
+ return errors.New("offline")
+ }
+ cmd, _, errOut := agentToolsCommand(t)
+ connectCloudMCPFromOnboarding(cmd)
+ if !got.yes || got.dryRun || got.force || got.tokenEnv != "" || len(got.harnesses) != 0 || got.url != "" {
+ t.Fatalf("request = %+v", got)
+ }
+ if !strings.Contains(errOut.String(), "offline") || !strings.Contains(errOut.String(), "beacon mcp connect") {
+ t.Fatalf("stderr: %s", errOut)
+ }
+}
+
+func newSkillsHome(t *testing.T) string {
t.Helper()
home := t.TempDir()
testenv.SetHome(t, home)
- t.Setenv("XDG_CONFIG_HOME", "")
t.Setenv("CLAUDE_CONFIG_DIR", "")
- t.Setenv("CODEX_HOME", "")
if err := os.Mkdir(filepath.Join(home, ".claude"), 0o700); err != nil {
t.Fatal(err)
}
- prevHome, prevExe := agentToolsHome, agentToolsExecutable
- prevDiscover, prevLook, prevRun := mcpDiscover, mcpLookPath, mcpRunCLI
- prevHarnesses := mcpConnectOpts.harnesses
+ prev := agentToolsHome
agentToolsHome = func() (string, error) { return home, nil }
- agentToolsExecutable = func() string { return "/opt/beacon/bin/beacon" }
- mcpDiscover = func() []harness.Harness {
- return []harness.Harness{
- {Name: "cursor", DisplayName: "Cursor", Detected: true},
- {Name: "gemini_cli", DisplayName: "Gemini CLI", Detected: true},
- {Name: "codex_cli", DisplayName: "Codex CLI", Detected: false},
- }
- }
- mcpLookPath = func(string) (string, error) { return "", errors.New("not on PATH") }
- mcpRunCLI = func(context.Context, string, ...string) ([]byte, error) {
- return nil, errors.New("no harness CLI may run here")
- }
- mcpConnectOpts.harnesses = nil
- t.Cleanup(func() {
- agentToolsHome, agentToolsExecutable = prevHome, prevExe
- mcpDiscover, mcpLookPath, mcpRunCLI = prevDiscover, prevLook, prevRun
- mcpConnectOpts.harnesses = prevHarnesses
- })
- f := agentToolsFixture{home: home, cmd: &cobra.Command{}, out: &bytes.Buffer{}, err: &bytes.Buffer{}}
- f.cmd.SetOut(f.out)
- f.cmd.SetErr(f.err)
- f.cmd.SetContext(context.Background())
- return f
+ t.Cleanup(func() { agentToolsHome = prev })
+ return home
}
-func TestInstallAgentToolsRegistersMCPAndInstallsSkills(t *testing.T) {
- f := newAgentToolsFixture(t)
- installAgentTools(f.cmd, onboardingOutcome{InstallMCP: true, InstallSkills: true})
- if f.err.Len() != 0 {
- t.Fatalf("stderr: %s", f.err)
- }
- for _, rel := range []string{".cursor/mcp.json", ".gemini/settings.json"} {
- data, err := os.ReadFile(filepath.Join(f.home, rel))
- if err != nil {
- t.Fatal(err)
- }
- if !strings.Contains(string(data), `"beacon"`) || !strings.Contains(string(data), "/opt/beacon/bin/beacon") {
- t.Fatalf("%s:\n%s", rel, data)
- }
- }
- // A harness that was not detected is not configured.
- if _, err := os.Stat(filepath.Join(f.home, ".codex", "config.toml")); !os.IsNotExist(err) {
- t.Fatalf("codex config written for an undetected harness (err=%v)", err)
+func TestOnboardingInstallsSkillsWhenKept(t *testing.T) {
+ home := newSkillsHome(t)
+ cmd, out, errOut := agentToolsCommand(t)
+ installAgentSkillsFromOnboarding(cmd, onboardingOutcome{InstallSkills: true})
+ if errOut.Len() != 0 {
+ t.Fatalf("stderr: %s", errOut)
}
for _, root := range []string{".agents/skills", ".claude/skills"} {
for _, name := range agentskills.Names() {
- if _, err := os.Stat(filepath.Join(f.home, root, name, "SKILL.md")); err != nil {
+ if _, err := os.Stat(filepath.Join(home, root, name, "SKILL.md")); err != nil {
t.Fatalf("%s/%s not installed: %v", root, name, err)
}
}
}
- out := f.out.String()
- for _, want := range []string{"registered for Cursor", "registered for Gemini CLI", "installed in ~/.agents/skills", "installed in ~/.claude/skills"} {
- if !strings.Contains(out, want) {
+ for _, want := range []string{"installed in ~/.agents/skills", "installed in ~/.claude/skills"} {
+ if !strings.Contains(out.String(), want) {
t.Fatalf("output missing %q:\n%s", want, out)
}
}
-
- // Both are undone by their uninstall commands.
- if err := runMCPUninstall(f.cmd, nil); err != nil {
- t.Fatal(err)
- }
- if err := runSkillsUninstall(f.cmd, nil); err != nil {
+ if err := runSkillsUninstall(cmd, nil); err != nil {
t.Fatal(err)
}
- for _, rel := range []string{".cursor/mcp.json", ".gemini/settings.json", ".agents/skills/beacon-memory-recall", ".claude/skills/beacon-memory-recall"} {
- if _, err := os.Stat(filepath.Join(f.home, rel)); !os.IsNotExist(err) {
- t.Fatalf("%s still present after uninstall (err=%v)", rel, err)
+ for _, root := range []string{".agents/skills", ".claude/skills"} {
+ if entries, _ := os.ReadDir(filepath.Join(home, root)); len(entries) != 0 {
+ t.Fatalf("%s not empty after uninstall: %v", root, entries)
}
}
}
-func TestDeclinedAgentToolsWriteNothing(t *testing.T) {
- f := newAgentToolsFixture(t)
- installAgentTools(f.cmd, onboardingOutcome{})
- for _, rel := range []string{".cursor", ".gemini", ".agents", ".claude/skills"} {
- if _, err := os.Stat(filepath.Join(f.home, rel)); !os.IsNotExist(err) {
- t.Fatalf("%s written although the agent tools were turned off (err=%v)", rel, err)
+func TestDeclinedSkillsWriteNothing(t *testing.T) {
+ home := newSkillsHome(t)
+ cmd, out, errOut := agentToolsCommand(t)
+ installAgentSkillsFromOnboarding(cmd, onboardingOutcome{})
+ for _, rel := range []string{".agents", ".claude/skills"} {
+ if _, err := os.Stat(filepath.Join(home, rel)); !os.IsNotExist(err) {
+ t.Fatalf("%s written although the skills were turned off (err=%v)", rel, err)
}
}
- if f.out.Len() != 0 || f.err.Len() != 0 {
- t.Fatalf("output: %q %q", f.out, f.err)
+ if out.Len() != 0 || errOut.Len() != 0 {
+ t.Fatalf("output: %q %q", out, errOut)
}
}
func TestRefreshAgentSkillsOnlyUpdatesInstalledCopies(t *testing.T) {
- f := newAgentToolsFixture(t)
+ home := newSkillsHome(t)
prevOpts := endpointOpts
prevRoot := onboardingIsRoot
endpointOpts.userMode, endpointOpts.systemMode = true, false
onboardingIsRoot = func() bool { return false }
t.Cleanup(func() { endpointOpts, onboardingIsRoot = prevOpts, prevRoot })
+ var out, errOut bytes.Buffer
- refreshAgentSkills(f.err)
- if _, err := os.Stat(filepath.Join(f.home, ".agents")); !os.IsNotExist(err) {
+ refreshAgentSkills(&errOut)
+ if _, err := os.Stat(filepath.Join(home, ".agents")); !os.IsNotExist(err) {
t.Fatalf("refresh installed skills nobody asked for (err=%v)", err)
}
- if err := installAgentSkills(f.out); err != nil {
+ if err := installAgentSkills(&out); err != nil {
t.Fatal(err)
}
- stale := filepath.Join(f.home, ".agents", "skills", "beacon-memory-recall", "SKILL.md")
+ stale := filepath.Join(home, ".agents", "skills", "beacon-memory-recall", "SKILL.md")
if err := os.WriteFile(stale, []byte("old"), 0o644); err != nil {
t.Fatal(err)
}
- refreshAgentSkills(f.err)
+ refreshAgentSkills(&errOut)
if data, _ := os.ReadFile(stale); string(data) == "old" {
t.Fatal("refresh left a stale skill")
}
- if f.err.Len() != 0 {
- t.Fatalf("stderr: %s", f.err)
+ if errOut.Len() != 0 {
+ t.Fatalf("stderr: %s", errOut.String())
+ }
+}
+
+func TestFinishCloudSetupRegistersMCPOnlyAfterConnectSucceeds(t *testing.T) {
+ prev := agentToolsConnectCloudMCP
+ t.Cleanup(func() { agentToolsConnectCloudMCP = prev })
+ for _, tc := range []struct {
+ name string
+ outcome onboardingOutcome
+ connect bool // connectAfterInstall
+ connectErr error
+ wantMCP bool
+ wantStderr string
+ wantStdout string
+ }{
+ {"connect then MCP", onboardingOutcome{Connect: true, ConnectCloudMCP: true}, true, nil, true, "", ""},
+ {"failed connect skips MCP", onboardingOutcome{Connect: true, ConnectCloudMCP: true}, true, errors.New("enroll failed"), false, "Beacon Cloud MCP was not registered either", ""},
+ {"MCP turned off suggests it", onboardingOutcome{Connect: true}, true, nil, false, "", "beacon mcp connect"},
+ {"already connected endpoint", onboardingOutcome{ConnectCloudMCP: true}, false, nil, true, "", ""},
+ {"local", onboardingOutcome{}, false, nil, false, "", ""},
+ } {
+ h := newOnboardingHarness(t)
+ h.loaded = onboarding.Profile{Onboarding: onboarding.Onboarding{CompletedAt: "2026-10-05T00:00:00Z"}}
+ ran := false
+ agentToolsConnectCloudMCP = func(context.Context, io.Writer, cloudMCPRequest) error {
+ ran = true
+ return nil
+ }
+ connected := false
+ finishCloudSetup(h.cmd, tc.outcome, tc.connect, func() error {
+ connected = true
+ return tc.connectErr
+ })
+ if connected != tc.connect {
+ t.Fatalf("%s: connect ran = %t", tc.name, connected)
+ }
+ if ran != tc.wantMCP {
+ t.Fatalf("%s: Beacon Cloud MCP ran = %t, want %t", tc.name, ran, tc.wantMCP)
+ }
+ if tc.wantStderr != "" && !strings.Contains(h.stderr.String(), tc.wantStderr) {
+ t.Fatalf("%s: stderr = %q", tc.name, h.stderr)
+ }
+ if tc.wantStdout != "" && !strings.Contains(h.stdout.String(), tc.wantStdout) {
+ t.Fatalf("%s: stdout = %q", tc.name, h.stdout)
+ }
+ if tc.wantStdout == "" && strings.Contains(h.stdout.String(), "run `beacon mcp connect`") {
+ t.Fatalf("%s: suggested mcp connect although it was registered or not applicable: %q", tc.name, h.stdout)
+ }
}
}
diff --git a/cli/beacon/cmd/endpoint_install.go b/cli/beacon/cmd/endpoint_install.go
index e4025ffd..1a030e73 100644
--- a/cli/beacon/cmd/endpoint_install.go
+++ b/cli/beacon/cmd/endpoint_install.go
@@ -180,24 +180,46 @@ func runEndpointInstall(cmd *cobra.Command, args []string) error {
printLingerGap(cmd.ErrOrStderr(), result)
installHookTargetsFromEndpointInstall(cmd.ErrOrStderr(), selection.Hooks)
refreshAgentSkills(cmd.ErrOrStderr())
- installAgentTools(cmd, onboarded)
- if connectAfterInstall {
- // The install is complete and stands on its own; a failed connect is reported
- // with the retry command rather than turning a working install into an error.
- fmt.Fprintln(cmd.OutOrStdout())
- if err := connectEndpoint(cmd, endpointUserMode(), result.LogPath); err != nil {
- fmt.Fprintf(cmd.ErrOrStderr(), "beacon: managed ingest was not connected (%v). Run `beacon endpoint connect` to try again.\n", err)
- } else {
- recordDestinationAsymptote(cmd)
- suggestMCPConnect(cmd.OutOrStdout(), onboarded.Connect)
+ installAgentSkillsFromOnboarding(cmd, onboarded)
+ finishCloudSetup(cmd, onboarded, connectAfterInstall, func() error {
+ return connectEndpoint(cmd, endpointUserMode(), result.LogPath)
+ })
+ return nil
+}
+
+// finishCloudSetup connects the endpoint when the wizard or --connect asked for it, and then
+// registers Beacon Cloud MCP when the wizard kept it selected. MCP is registered only once the
+// endpoint forwards to Beacon Cloud, since there is nothing for it to search otherwise.
+func finishCloudSetup(cmd *cobra.Command, onboarded onboardingOutcome, connectAfterInstall bool, connect func() error) {
+ if !connectAfterInstall {
+ if onboarded.ConnectCloudMCP {
+ // An endpoint that was already connected keeps its device key and is not
+ // re-enrolled, but the person still asked for Beacon Cloud MCP.
+ connectCloudMCPFromOnboarding(cmd)
}
+ return
}
- return nil
+ // The install is complete and stands on its own; a failed connect is reported with the
+ // retry command rather than turning a working install into an error.
+ fmt.Fprintln(cmd.OutOrStdout())
+ if err := connect(); err != nil {
+ fmt.Fprintf(cmd.ErrOrStderr(), "beacon: managed ingest was not connected (%v). Run `beacon endpoint connect` to try again.\n", err)
+ if onboarded.ConnectCloudMCP {
+ fmt.Fprintln(cmd.ErrOrStderr(), "beacon: Beacon Cloud MCP was not registered either; run `beacon mcp connect` once the endpoint is connected.")
+ }
+ return
+ }
+ recordDestinationAsymptote(cmd)
+ if onboarded.ConnectCloudMCP {
+ connectCloudMCPFromOnboarding(cmd)
+ return
+ }
+ suggestMCPConnect(cmd.OutOrStdout(), onboarded.Connect)
}
-// suggestMCPConnect points a person who just chose Beacon Cloud in the wizard at
-// `beacon mcp connect`. It only prints: registering the MCP server stays a separate,
-// explicit command, and the unattended install paths never reach the wizard at all.
+// suggestMCPConnect points a person who chose Beacon Cloud in the wizard, but turned Beacon
+// Cloud MCP off, at `beacon mcp connect`. It only prints, and the unattended install paths never
+// reach the wizard at all.
func suggestMCPConnect(out io.Writer, chosenInWizard bool) {
if !chosenInWizard {
return
diff --git a/cli/beacon/cmd/endpoint_onboarding.go b/cli/beacon/cmd/endpoint_onboarding.go
index ca079006..96911580 100644
--- a/cli/beacon/cmd/endpoint_onboarding.go
+++ b/cli/beacon/cmd/endpoint_onboarding.go
@@ -104,11 +104,12 @@ type onboardingOutcome struct {
// machine marked onboarded, so the retry took the already-completed branch, said
// nothing, and never offered the destination again.
Persist func() error
- // InstallMCP and InstallSkills are the agent tools the person kept selected. They are
- // offered whichever destination was chosen, and installed after lifecycle.Install
- // returns, like everything else the wizard decided.
- InstallMCP bool
- InstallSkills bool
+ // ConnectCloudMCP and InstallSkills are the agent tools the person kept selected, acted
+ // on after lifecycle.Install returns like everything else the wizard decided. The skills
+ // are offered whichever destination was chosen; Beacon Cloud MCP only with Beacon Cloud,
+ // and it is registered only once the endpoint forwards there.
+ ConnectCloudMCP bool
+ InstallSkills bool
}
// maybeRunOnboarding runs the one-time account and destination wizard when this
@@ -263,11 +264,15 @@ func runAccountOnboarding(cmd *cobra.Command, profile *onboarding.Profile, desti
}
decided := onboardingOutcome{
- Connect: connectAfterInstall,
- InstallMCP: result.InstallMCP,
- InstallSkills: result.InstallSkills,
+ Connect: connectAfterInstall,
+ ConnectCloudMCP: result.Destination == onboarding.DestinationAsymptote && result.ConnectCloudMCP,
+ InstallSkills: result.InstallSkills,
+ }
+ // Beacon Cloud MCP is only asked with Beacon Cloud, so a Local run records no answer.
+ cloudMCPAnswer := ""
+ if result.Destination == onboarding.DestinationAsymptote {
+ cloudMCPAnswer = onboarding.AgentToolAnswer(decided.ConnectCloudMCP)
}
- mcpAnswer := onboarding.AgentToolAnswer(result.InstallMCP)
skillsAnswer := onboarding.AgentToolAnswer(result.InstallSkills)
email := status.User.Email
// A run that never signed in is recorded as skipped, not authenticated.
@@ -284,14 +289,14 @@ func runAccountOnboarding(cmd *cobra.Command, profile *onboarding.Profile, desti
BeaconVersion: version.GetVersion(),
Destination: recordedDestination,
PrivacyMode: privacyMode,
- MCPServer: mcpAnswer,
+ CloudMCP: cloudMCPAnswer,
AgentSkills: skillsAnswer,
}
profile.Pending = nil
} else {
profile.Onboarding.Destination = recordedDestination
profile.Onboarding.PrivacyMode = privacyMode
- profile.Onboarding.MCPServer = mcpAnswer
+ profile.Onboarding.CloudMCP = cloudMCPAnswer
profile.Onboarding.AgentSkills = skillsAnswer
}
if _, err := onboarding.EnsureInstallID(profile); err != nil {
@@ -554,7 +559,7 @@ type endpointOnboardingStatus struct {
BeaconVersion string `json:"beacon_version,omitempty"`
Destination string `json:"destination,omitempty"`
PrivacyMode string `json:"privacy_mode,omitempty"`
- MCPServer string `json:"mcp_server,omitempty"`
+ CloudMCP string `json:"cloud_mcp,omitempty"`
AgentSkills string `json:"agent_skills,omitempty"`
Pending bool `json:"pending_submission"`
SkipReason string `json:"skip_reason,omitempty"`
@@ -596,7 +601,7 @@ func runEndpointOnboarding(cmd *cobra.Command, args []string) error {
BeaconVersion: profile.Onboarding.BeaconVersion,
Destination: profile.Onboarding.Destination,
PrivacyMode: profile.Onboarding.PrivacyMode,
- MCPServer: profile.Onboarding.MCPServer,
+ CloudMCP: profile.Onboarding.CloudMCP,
AgentSkills: profile.Onboarding.AgentSkills,
Pending: profile.Pending != nil,
SkipReason: reason,
@@ -628,8 +633,8 @@ func runEndpointOnboarding(cmd *cobra.Command, args []string) error {
if status.PrivacyMode != "" {
fmt.Fprintf(out, "Managed privacy: %s\n", managedprivacy.Label(status.PrivacyMode))
}
- if status.MCPServer != "" {
- fmt.Fprintf(out, "Beacon MCP server: %s\n", status.MCPServer)
+ if status.CloudMCP != "" {
+ fmt.Fprintf(out, "Beacon Cloud MCP: %s\n", status.CloudMCP)
}
if status.AgentSkills != "" {
fmt.Fprintf(out, "Beacon agent skills: %s\n", status.AgentSkills)
diff --git a/cli/beacon/cmd/mcp.go b/cli/beacon/cmd/mcp.go
index 8983b3af..a3cc7206 100644
--- a/cli/beacon/cmd/mcp.go
+++ b/cli/beacon/cmd/mcp.go
@@ -34,7 +34,7 @@ var mcpCmd = &cobra.Command{
Long: `Expose Beacon activity through MCP.
serve and doctor run and check the local "beacon" server, which reads this machine's runtime
-log; install and uninstall register it in your harnesses or remove it. connect, disconnect and status manage the "beacon-managed" entry that points your harnesses
+log. connect, disconnect and status manage the "beacon-managed" entry that points your harnesses
at Beacon Cloud MCP, which searches the session history this endpoint forwards.`,
}
diff --git a/cli/beacon/cmd/mcp_connect.go b/cli/beacon/cmd/mcp_connect.go
index ff47cd37..fd6911ff 100644
--- a/cli/beacon/cmd/mcp_connect.go
+++ b/cli/beacon/cmd/mcp_connect.go
@@ -24,8 +24,10 @@ import (
)
// `beacon mcp connect` registers the Beacon Cloud MCP server in the harnesses on this machine.
-// It is an explicit, interactive, per-user command: `beacon endpoint install`, onboarding and
-// every unattended path (root, system/MDM installs, CI, piped stdin) never run it. It writes no
+// It is an explicit, per-user command. The one other caller is the interactive onboarding
+// wizard, which runs the same flow after the person chose Beacon Cloud and left "Beacon Cloud
+// MCP" selected on its agent tools screen; that screen is the confirmation. Every unattended path
+// (root, system/MDM installs, CI, piped stdin) never reaches it. It writes no
// secret -- OAuth harnesses get only the URL, and --token-env writes a reference to a variable --
// and it never reads the Beacon account token in ~/.beacon/auth/session.json. Its only network
// request is the resource-metadata check of the URL, which --dry-run skips.
@@ -203,12 +205,27 @@ func mcpTargetNames() []string {
}
func mcpOptions(home, url string) mcpconnect.Options {
+ return mcpOptionsFor(home, url, mcpConnectOpts.tokenEnv, mcpConnectOpts.force)
+}
+
+func mcpOptionsFor(home, url, tokenEnv string, force bool) mcpconnect.Options {
return mcpconnect.Options{
- Home: home, URL: url, TokenEnv: mcpConnectOpts.tokenEnv, Force: mcpConnectOpts.force,
+ Home: home, URL: url, TokenEnv: tokenEnv, Force: force,
LookPath: mcpLookPath, Run: mcpRunCLI,
}
}
+// cloudMCPRequest is one run of the connect flow: the flags of `beacon mcp connect`, or what
+// onboarding asks for (detected harnesses, OAuth, already confirmed).
+type cloudMCPRequest struct {
+ harnesses []string
+ url string
+ tokenEnv string
+ dryRun bool
+ yes bool
+ force bool
+}
+
// connectRefusal is why connect will not run here, or "" when it may.
func connectRefusal() string {
switch {
@@ -225,28 +242,38 @@ func connectRefusal() string {
}
func runMCPConnect(cmd *cobra.Command, args []string) error {
- out := cmd.OutOrStdout()
if reason := connectRefusal(); reason != "" {
return errors.New(reason)
}
- if err := validateTokenEnv(mcpConnectOpts.tokenEnv); err != nil {
+ return connectCloudMCP(commandContext(cmd), cmd.OutOrStdout(), cloudMCPRequest{
+ harnesses: mcpConnectOpts.harnesses,
+ url: mcpConnectOpts.url,
+ tokenEnv: mcpConnectOpts.tokenEnv,
+ dryRun: mcpConnectOpts.dryRun,
+ yes: mcpConnectOpts.yes,
+ force: mcpConnectOpts.force,
+ })
+}
+
+func connectCloudMCP(ctx context.Context, out io.Writer, req cloudMCPRequest) error {
+ if err := validateTokenEnv(req.tokenEnv); err != nil {
return err
}
home, err := mcpHome()
if err != nil {
return err
}
- targets, unsupported, err := resolveMCPTargets(mcpConnectOpts.harnesses)
+ targets, unsupported, err := resolveMCPTargets(req.harnesses)
if err != nil {
return err
}
- url, derived, err := mcpconnect.ResolveURL(mcpConnectOpts.url, mcpIngestURL())
+ url, derived, err := mcpconnect.ResolveURL(req.url, mcpIngestURL())
if err != nil {
return fmt.Errorf("%w (Beacon Cloud serves MCP at https://mcp.beacon.sh)", err)
}
checked := "not checked (--dry-run)"
- if !mcpConnectOpts.dryRun {
- canonical, err := mcpconnect.CheckURL(cmd.Context(), mcpHTTPClient, url, derived)
+ if !req.dryRun {
+ canonical, err := mcpconnect.CheckURL(ctx, mcpHTTPClient, url, derived)
if err != nil {
return fmt.Errorf("the MCP URL check failed, so nothing was written: %w", err)
}
@@ -257,7 +284,7 @@ func runMCPConnect(cmd *cobra.Command, args []string) error {
printUnsupported(out, unsupported)
return nil
}
- opts := mcpOptions(home, url)
+ opts := mcpOptionsFor(home, url, req.tokenEnv, req.force)
plan, err := mcpconnect.Plan(opts, targets)
if err != nil {
return err
@@ -281,7 +308,7 @@ func runMCPConnect(cmd *cobra.Command, args []string) error {
writes++
}
}
- if mcpConnectOpts.dryRun {
+ if req.dryRun {
fmt.Fprintln(out, "\nDry run: nothing was written.")
return nil
}
@@ -290,14 +317,14 @@ func runMCPConnect(cmd *cobra.Command, args []string) error {
printNextSteps(out, plan, opts)
return nil
}
- if !mcpConnectOpts.yes {
+ if !req.yes {
fmt.Fprintf(out, "\nWrite %d change(s)? Each changed file is backed up first. [y/N] ", writes)
if !confirmNo(mcpStdin) {
fmt.Fprintln(out, "Nothing was written.")
return nil
}
}
- applied, err := mcpconnect.Apply(cmd.Context(), opts, plan)
+ applied, err := mcpconnect.Apply(ctx, opts, plan)
if err != nil {
return err
}
diff --git a/cli/beacon/internal/mcpconnect/engine.go b/cli/beacon/internal/mcpconnect/engine.go
index b72a3ef4..92774a14 100644
--- a/cli/beacon/internal/mcpconnect/engine.go
+++ b/cli/beacon/internal/mcpconnect/engine.go
@@ -111,11 +111,6 @@ type state struct {
}
func inspect(t Target, path string) (state, error) {
- return inspectNamed(t, path, ServerName)
-}
-
-// inspectNamed reads what a config holds under one server name.
-func inspectNamed(t Target, path, name string) (state, error) {
var st state
cf, err := readConfig(path)
if err != nil {
@@ -134,7 +129,7 @@ func inspectNamed(t Target, path, name string) (state, error) {
return st, fmt.Errorf("%s: %q is not a table", path, t.container[0])
}
}
- st.entry, st.exists = tomlTableEntry(parsed, t.container[0], name)
+ st.entry, st.exists = tomlTableEntry(parsed, t.container[0], ServerName)
default:
parsed, err := decodeJSONC(cf.text)
if err != nil {
@@ -146,12 +141,12 @@ func inspectNamed(t Target, path, name string) (state, error) {
if err != nil {
return st, fmt.Errorf("%s: %v", path, err)
}
- if len(chain) == len(t.container)+1 && chain[len(chain)-1].memberCount(name) > 1 {
- return st, fmt.Errorf("%s: %q appears more than once", path, name)
+ if len(chain) == len(t.container)+1 && chain[len(chain)-1].memberCount(ServerName) > 1 {
+ return st, fmt.Errorf("%s: %q appears more than once", path, ServerName)
}
}
container := dig(parsed, t.container)
- if raw, ok := container[name]; ok {
+ if raw, ok := container[ServerName]; ok {
st.exists = true
st.entry, _ = raw.(map[string]any)
if st.entry == nil {
diff --git a/cli/beacon/internal/mcpconnect/local.go b/cli/beacon/internal/mcpconnect/local.go
deleted file mode 100644
index f630a5ee..00000000
--- a/cli/beacon/internal/mcpconnect/local.go
+++ /dev/null
@@ -1,284 +0,0 @@
-package mcpconnect
-
-import (
- "context"
- "errors"
- "fmt"
- "path/filepath"
- "reflect"
- "strings"
- "time"
-)
-
-// The local stdio server, `beacon mcp serve`, reads this machine's runtime log. Onboarding
-// registers it in every detected harness unless the person opts out, so an agent can search its
-// own history whichever destination was chosen. It is a different entry from Beacon Cloud MCP
-// (ServerName) and has its own manifest, so `beacon mcp connect` and `disconnect` never touch it
-// and removing it never touches theirs.
-//
-// The policy is narrower than connect's: Beacon adds the entry where the name is free and never
-// replaces one that is already there, whoever wrote it. Nothing here touches the network.
-
-// LocalServerName is the name the local stdio server is registered under.
-const LocalServerName = "beacon"
-
-// LocalManifestPath is the file under the home directory that records the local entries Beacon
-// wrote.
-const LocalManifestPath = ".beacon/mcp/local.json"
-
-// LocalOptions configures registering the local server.
-type LocalOptions struct {
- Home string
- // Command is the beacon executable the harness runs, as an absolute path: harnesses started
- // from a desktop launcher do not see a shell's PATH.
- Command string
-
- LookPath func(string) (string, error)
- Run func(ctx context.Context, name string, args ...string) ([]byte, error)
-}
-
-func (o LocalOptions) connectOptions() Options {
- return Options{Home: o.Home, LookPath: o.LookPath, Run: o.Run}
-}
-
-var timeNow = time.Now
-
-func localArgs() []any {
- return []any{"mcp", "serve"}
-}
-
-// LocalSupported reports whether Beacon can register the local server in t.
-func (t Target) LocalSupported() bool {
- return t.Automatic && t.localEntry != nil
-}
-
-// InstallLocal registers the local server in each target that supports it. Each target is
-// independent: a failure is reported on its item and the rest still run.
-func InstallLocal(ctx context.Context, opts LocalOptions, targets []Target) ([]Item, error) {
- if strings.TrimSpace(opts.Command) == "" {
- return nil, errors.New("the beacon executable path is required")
- }
- manifestFile := filepath.Join(opts.Home, LocalManifestPath)
- m, err := loadManifestAt(manifestFile)
- if err != nil {
- return nil, err
- }
- copts := opts.connectOptions()
- var items []Item
- for _, t := range targets {
- if !t.LocalSupported() {
- continue
- }
- it := Item{Target: t, Method: "file"}
- path, err := t.path(opts.Home)
- if err != nil {
- it.Action, it.Detail = ActionSkip, err.Error()
- items = append(items, it)
- continue
- }
- it.Path = path
- st, err := inspectNamed(t, path, LocalServerName)
- if err != nil {
- it.Action, it.Detail = ActionSkip, err.Error()
- items = append(items, it)
- continue
- }
- if st.exists {
- it.Action, it.Detail = ActionPresent, "an entry named "+LocalServerName+" is already configured; left as is"
- items = append(items, it)
- continue
- }
- it.Action = ActionAdd
- if t.cli != "" {
- if cliPath, err := copts.lookPath(t.cli); err == nil {
- it.cliPath, it.Method = cliPath, t.cli+" CLI"
- }
- }
- rec, err := addLocal(ctx, opts, it, st)
- if err != nil {
- it.Err = err
- items = append(items, it)
- continue
- }
- m.put(rec)
- if err := m.saveAt(manifestFile); err != nil {
- it.Err = fmt.Errorf("the entry was written, but the record of it could not be saved (%w); `beacon mcp uninstall` will not remove it", err)
- }
- items = append(items, it)
- }
- return items, nil
-}
-
-func addLocal(ctx context.Context, opts LocalOptions, it Item, st state) (Record, error) {
- t := it.Target
- entry := t.localEntry(opts.Command)
- rec := Record{Harness: t.Name, Path: it.Path, ServerName: LocalServerName, Command: opts.Command, Method: "file"}
- if it.cliPath != "" {
- rec.Method = t.cli + "-cli"
- backup, err := st.file.backup(timeNow())
- if err != nil {
- return Record{}, fmt.Errorf("could not back up %s: %w", it.Path, err)
- }
- rec.Backup = backup
- args := []string{"mcp", "add", "--scope", "user", LocalServerName, "--", opts.Command}
- for _, a := range localArgs() {
- args = append(args, fmt.Sprint(a))
- }
- if out, err := opts.connectOptions().run(ctx, it.cliPath, args...); err != nil {
- return Record{}, fmt.Errorf("`%s mcp add` failed: %v: %s", t.cli, err, strings.TrimSpace(string(out)))
- }
- after, err := inspectNamed(t, it.Path, LocalServerName)
- if err != nil {
- return Record{}, err
- }
- if !after.exists || !sameLocalCommand(t, after.entry, opts.Command) {
- return Record{}, fmt.Errorf("`%s mcp add` ran, but %s does not hold the expected %s entry", t.cli, it.Path, LocalServerName)
- }
- return rec, nil
- }
-
- cf := st.file
- var updated string
- if t.format == formatTOML {
- eol := tomlLineEnding(cf.text)
- updated = appendTOMLBlock(cf.text, tomlBlock(t.container[0], LocalServerName, entry, eol), eol)
- } else {
- updated = cf.text
- if strings.TrimSpace(updated) == "" && len(t.skeleton) > 0 {
- updated = renderJSONDocument(t.skeleton, detectJSONStyle(cf.text))
- }
- var err error
- if updated, rec.CreatedParents, err = insertJSONMember(updated, t.container, LocalServerName, entry); err != nil {
- return Record{}, fmt.Errorf("could not edit %s: %w", it.Path, err)
- }
- }
- b, a, err := parseBoth(t, cf.text, updated)
- if err != nil {
- return Record{}, fmt.Errorf("%s: %w; the file was left unchanged", it.Path, err)
- }
- if strings.TrimSpace(cf.text) == "" {
- for _, f := range t.skeleton {
- b[f.Key] = normalizeJSON(f.Value)
- }
- }
- setPath(b, t.container, LocalServerName, normalizeJSON(entry))
- if !reflect.DeepEqual(normalizeValue(b), normalizeValue(a)) {
- return Record{}, fmt.Errorf("%s: Beacon's edit would have changed more than its own %s entry; the file was left unchanged", it.Path, LocalServerName)
- }
- backup, err := cf.backup(timeNow())
- if err != nil {
- return Record{}, fmt.Errorf("could not back up %s: %w", it.Path, err)
- }
- rec.Backup, rec.CreatedFile = backup, !cf.exists
- if err := cf.write(updated); err != nil {
- return Record{}, fmt.Errorf("could not write %s: %w", it.Path, err)
- }
- rec.AfterSHA256 = digest(updated)
- return rec, nil
-}
-
-// sameLocalCommand reports whether an entry runs command with the local server's arguments,
-// whatever else the harness added to it (Claude Code writes an empty "env").
-func sameLocalCommand(t Target, entry map[string]any, command string) bool {
- want, _ := normalizeJSON(t.localEntry(command)).(map[string]any)
- for _, key := range []string{"command", "args"} {
- if !reflect.DeepEqual(normalizeValue(entry[key]), normalizeValue(want[key])) {
- return false
- }
- }
- return true
-}
-
-// UninstallLocal removes the local entries Beacon recorded, and only while each still runs the
-// command Beacon wrote: an entry someone has since changed is theirs.
-func UninstallLocal(ctx context.Context, opts LocalOptions) ([]Item, error) {
- manifestFile := filepath.Join(opts.Home, LocalManifestPath)
- m, err := loadManifestAt(manifestFile)
- if err != nil {
- return nil, err
- }
- copts := opts.connectOptions()
- var items []Item
- for _, rec := range append([]Record(nil), m.Records...) {
- t, ok := Lookup(rec.Harness)
- if !ok || !t.LocalSupported() {
- continue
- }
- it := Item{Target: t, Path: rec.Path, Method: rec.Method}
- it.Action, it.Detail, it.Err = removeLocal(ctx, copts, t, rec)
- if it.Err == nil {
- m.drop(rec.Harness, rec.Path)
- if err := m.saveAt(manifestFile); err != nil {
- it.Err = err
- }
- }
- items = append(items, it)
- }
- return items, nil
-}
-
-func removeLocal(ctx context.Context, opts Options, t Target, rec Record) (Action, string, error) {
- st, err := inspectNamed(t, rec.Path, LocalServerName)
- if err != nil {
- return ActionSkip, "", err
- }
- if !st.exists {
- return ActionAbsent, "the entry is already gone", nil
- }
- if !sameLocalCommand(t, st.entry, rec.Command) {
- return ActionAbsent, "the " + LocalServerName + " entry was changed after Beacon wrote it; left alone", nil
- }
- if rec.Method == t.cli+"-cli" && t.cli != "" {
- if cliPath, err := opts.lookPath(t.cli); err == nil {
- if out, err := opts.run(ctx, cliPath, "mcp", "remove", LocalServerName, "--scope", "user"); err != nil {
- return ActionSkip, "", fmt.Errorf("`%s mcp remove` failed: %v: %s", t.cli, err, strings.TrimSpace(string(out)))
- }
- after, err := inspectNamed(t, rec.Path, LocalServerName)
- if err != nil {
- return ActionSkip, "", err
- }
- if after.exists {
- return ActionSkip, "", fmt.Errorf("`%s mcp remove` ran, but %s still holds %s", t.cli, rec.Path, LocalServerName)
- }
- return ActionRemove, "removed with `" + t.cli + " mcp remove`", nil
- }
- }
- cf := st.file
- var updated string
- if t.format == formatTOML {
- stripped, found := stripTOMLTable(cf.text, t.container[0], LocalServerName)
- if !found {
- return ActionSkip, "", errors.New("the " + LocalServerName + " entry is not a [" + t.container[0] + "." + LocalServerName + "] table; remove it by hand")
- }
- updated = endTOMLWithNewline(stripped, tomlLineEnding(cf.text))
- } else {
- if updated, err = removeJSONMember(cf.text, t.container, LocalServerName, rec.CreatedParents); err != nil {
- return ActionSkip, "", fmt.Errorf("could not edit %s: %w", rec.Path, err)
- }
- }
- b, a, err := parseBoth(t, cf.text, updated)
- if err != nil {
- return ActionSkip, "", err
- }
- deletePath(b, t.container, LocalServerName, rec.CreatedParents)
- if t.format == formatTOML {
- dropEmptyTable(b, t.container[0])
- dropEmptyTable(a, t.container[0])
- }
- if !reflect.DeepEqual(normalizeValue(b), normalizeValue(a)) {
- return ActionSkip, "", fmt.Errorf("%s: Beacon's edit would have changed more than its own %s entry; the file was left unchanged", rec.Path, LocalServerName)
- }
- if rec.CreatedFile && onlySkeleton(t, updated) {
- if err := cf.remove(); err != nil {
- return ActionSkip, "", err
- }
- return ActionRemove, "removed the file Beacon created", nil
- }
- if _, err := cf.backup(timeNow()); err != nil {
- return ActionSkip, "", fmt.Errorf("could not back up %s: %w", rec.Path, err)
- }
- if err := cf.write(updated); err != nil {
- return ActionSkip, "", err
- }
- return ActionRemove, "removed Beacon's entry", nil
-}
diff --git a/cli/beacon/internal/mcpconnect/local_test.go b/cli/beacon/internal/mcpconnect/local_test.go
deleted file mode 100644
index 3e6516fd..00000000
--- a/cli/beacon/internal/mcpconnect/local_test.go
+++ /dev/null
@@ -1,222 +0,0 @@
-package mcpconnect
-
-import (
- "context"
- "errors"
- "os"
- "path/filepath"
- "strings"
- "testing"
-)
-
-const testBeacon = "/opt/beacon/bin/beacon"
-
-func localFileOptions(home string) LocalOptions {
- return LocalOptions{
- Home: home, Command: testBeacon,
- LookPath: func(string) (string, error) { return "", errors.New("not on PATH") },
- Run: func(context.Context, string, ...string) ([]byte, error) {
- return nil, errors.New("no CLI may run in file-writer tests")
- },
- }
-}
-
-func localTargets() []Target {
- var out []Target
- for _, t := range Targets() {
- if t.LocalSupported() {
- out = append(out, t)
- }
- }
- return out
-}
-
-func TestLocalSupportedOnEveryAutomaticTarget(t *testing.T) {
- for _, target := range Targets() {
- if target.Automatic != target.LocalSupported() {
- t.Errorf("%s: automatic=%t local=%t", target.Name, target.Automatic, target.LocalSupported())
- }
- }
-}
-
-func TestInstallLocalCreatesEachConfigAndUninstallRemovesIt(t *testing.T) {
- home := isolate(t)
- opts := localFileOptions(home)
- items, err := InstallLocal(context.Background(), opts, localTargets())
- if err != nil {
- t.Fatal(err)
- }
- if len(items) != len(localTargets()) {
- t.Fatalf("items = %d, want %d", len(items), len(localTargets()))
- }
- for _, it := range items {
- if it.Err != nil || it.Action != ActionAdd {
- t.Fatalf("%s: action=%s err=%v", it.Target.Name, it.Action, it.Err)
- }
- st, err := inspectNamed(it.Target, it.Path, LocalServerName)
- if err != nil {
- t.Fatal(err)
- }
- if !st.exists || !sameLocalCommand(it.Target, st.entry, testBeacon) {
- t.Fatalf("%s: entry = %#v", it.Target.Name, st.entry)
- }
- // Beacon Cloud MCP's entry is a different name and stays unconfigured.
- if cloud, _ := inspect(it.Target, it.Path); cloud.exists {
- t.Fatalf("%s: local install wrote %s", it.Target.Name, ServerName)
- }
- }
- codex, err := os.ReadFile(filepath.Join(home, ".codex", "config.toml"))
- if err != nil {
- t.Fatal(err)
- }
- if want := "[mcp_servers.beacon]\ncommand = \"/opt/beacon/bin/beacon\"\nargs = [\"mcp\", \"serve\"]\n"; string(codex) != want {
- t.Fatalf("codex config:\n%s\nwant:\n%s", codex, want)
- }
-
- // A second run finds every entry in place and writes nothing.
- again, err := InstallLocal(context.Background(), opts, localTargets())
- if err != nil {
- t.Fatal(err)
- }
- for _, it := range again {
- if it.Action != ActionPresent {
- t.Fatalf("%s: second run action = %s", it.Target.Name, it.Action)
- }
- }
-
- removed, err := UninstallLocal(context.Background(), opts)
- if err != nil {
- t.Fatal(err)
- }
- if len(removed) != len(localTargets()) {
- t.Fatalf("removed %d items, want %d", len(removed), len(localTargets()))
- }
- for _, it := range removed {
- if it.Err != nil || it.Action != ActionRemove {
- t.Fatalf("%s: action=%s err=%v", it.Target.Name, it.Action, it.Err)
- }
- if _, err := os.Stat(it.Path); !errors.Is(err, os.ErrNotExist) {
- t.Fatalf("%s: %s should be gone, Beacon created it (err=%v)", it.Target.Name, it.Path, err)
- }
- }
- if _, err := os.Stat(filepath.Join(home, LocalManifestPath)); !errors.Is(err, os.ErrNotExist) {
- t.Fatalf("empty local manifest should be removed (err=%v)", err)
- }
-}
-
-func TestInstallLocalKeepsExistingContentAndEntries(t *testing.T) {
- home := isolate(t)
- cursor := mustTarget(t, "cursor")
- path := targetPath(t, cursor, home)
- if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
- t.Fatal(err)
- }
- existing := `{
- // my servers
- "mcpServers": {
- "other": {"command": "other"}
- }
-}
-`
- if err := os.WriteFile(path, []byte(existing), 0o600); err != nil {
- t.Fatal(err)
- }
- items, err := InstallLocal(context.Background(), localFileOptions(home), []Target{cursor})
- if err != nil || len(items) != 1 || items[0].Err != nil {
- t.Fatalf("items=%+v err=%v", items, err)
- }
- data, _ := os.ReadFile(path)
- if !strings.Contains(string(data), "// my servers") || !strings.Contains(string(data), `"other": {"command": "other"}`) {
- t.Fatalf("existing content not preserved:\n%s", data)
- }
- if _, err := UninstallLocal(context.Background(), localFileOptions(home)); err != nil {
- t.Fatal(err)
- }
- after, _ := os.ReadFile(path)
- if string(after) != existing {
- t.Fatalf("uninstall did not restore the original content:\n%s", after)
- }
-}
-
-func TestInstallLocalNeverReplacesAnEntryNamedBeacon(t *testing.T) {
- home := isolate(t)
- gemini := mustTarget(t, "gemini_cli")
- path := targetPath(t, gemini, home)
- if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
- t.Fatal(err)
- }
- existing := `{"mcpServers": {"beacon": {"command": "/somewhere/else/beacon", "args": ["mcp", "serve"]}}}`
- if err := os.WriteFile(path, []byte(existing), 0o600); err != nil {
- t.Fatal(err)
- }
- items, err := InstallLocal(context.Background(), localFileOptions(home), []Target{gemini})
- if err != nil {
- t.Fatal(err)
- }
- if items[0].Action != ActionPresent {
- t.Fatalf("action = %s, want present", items[0].Action)
- }
- if data, _ := os.ReadFile(path); string(data) != existing {
- t.Fatalf("existing entry was changed:\n%s", data)
- }
- // Nothing was recorded, so uninstall leaves it alone too.
- removed, err := UninstallLocal(context.Background(), localFileOptions(home))
- if err != nil || len(removed) != 0 {
- t.Fatalf("removed=%+v err=%v", removed, err)
- }
-}
-
-func TestUninstallLocalLeavesAnEntryChangedAfterInstall(t *testing.T) {
- home := isolate(t)
- gemini := mustTarget(t, "gemini_cli")
- if _, err := InstallLocal(context.Background(), localFileOptions(home), []Target{gemini}); err != nil {
- t.Fatal(err)
- }
- path := targetPath(t, gemini, home)
- changed := `{"mcpServers": {"beacon": {"command": "/mine/beacon", "args": ["mcp", "serve"]}}}`
- if err := os.WriteFile(path, []byte(changed), 0o600); err != nil {
- t.Fatal(err)
- }
- removed, err := UninstallLocal(context.Background(), localFileOptions(home))
- if err != nil || len(removed) != 1 || removed[0].Action != ActionAbsent {
- t.Fatalf("removed=%+v err=%v", removed, err)
- }
- if data, _ := os.ReadFile(path); string(data) != changed {
- t.Fatalf("changed entry was touched:\n%s", data)
- }
-}
-
-func TestInstallLocalUsesClaudeCLIWhenPresent(t *testing.T) {
- home := isolate(t)
- claude := mustTarget(t, "claude_code")
- path := targetPath(t, claude, home)
- var calls [][]string
- opts := localFileOptions(home)
- opts.LookPath = func(name string) (string, error) { return "/usr/bin/" + name, nil }
- opts.Run = func(_ context.Context, name string, args ...string) ([]byte, error) {
- calls = append(calls, append([]string{name}, args...))
- switch args[1] {
- case "add":
- // What `claude mcp add --scope user beacon -- <cmd> mcp serve` writes.
- return nil, os.WriteFile(path, []byte(`{"mcpServers":{"beacon":{"type":"stdio","command":"`+testBeacon+`","args":["mcp","serve"],"env":{}}}}`), 0o600)
- case "remove":
- return nil, os.WriteFile(path, []byte(`{"mcpServers":{}}`), 0o600)
- }
- return nil, errors.New("unexpected")
- }
- items, err := InstallLocal(context.Background(), opts, []Target{claude})
- if err != nil || items[0].Err != nil || items[0].Method != "claude CLI" {
- t.Fatalf("items=%+v err=%v", items, err)
- }
- want := "/usr/bin/claude mcp add --scope user beacon -- " + testBeacon + " mcp serve"
- if got := strings.Join(calls[0], " "); got != want {
- t.Fatalf("call = %q, want %q", got, want)
- }
- removed, err := UninstallLocal(context.Background(), opts)
- if err != nil || len(removed) != 1 || removed[0].Action != ActionRemove || removed[0].Err != nil {
- t.Fatalf("removed=%+v err=%v", removed, err)
- }
- if got := strings.Join(calls[1], " "); got != "/usr/bin/claude mcp remove beacon --scope user" {
- t.Fatalf("remove call = %q", got)
- }
-}
diff --git a/cli/beacon/internal/mcpconnect/manifest.go b/cli/beacon/internal/mcpconnect/manifest.go
index ca605af7..1d00a9f4 100644
--- a/cli/beacon/internal/mcpconnect/manifest.go
+++ b/cli/beacon/internal/mcpconnect/manifest.go
@@ -26,15 +26,13 @@ const manifestSchemaVersion = 1
// Record is one entry Beacon wrote into one harness config.
type Record struct {
- Harness string `json:"harness"`
- Path string `json:"path"`
- ServerName string `json:"server_name"`
- URL string `json:"url"`
- // Command is the executable a local stdio entry runs; empty for Beacon Cloud entries.
- Command string `json:"command,omitempty"`
- Auth AuthMode `json:"auth"`
- TokenEnv string `json:"token_env,omitempty"`
- Method string `json:"method"`
+ Harness string `json:"harness"`
+ Path string `json:"path"`
+ ServerName string `json:"server_name"`
+ URL string `json:"url"`
+ Auth AuthMode `json:"auth"`
+ TokenEnv string `json:"token_env,omitempty"`
+ Method string `json:"method"`
// CreatedFile is set when the config did not exist before connect, so disconnect can remove a
// file that holds nothing else.
CreatedFile bool `json:"created_file,omitempty"`
@@ -60,11 +58,7 @@ func manifestPath(home string) string {
}
func loadManifest(home string) (*manifest, error) {
- return loadManifestAt(manifestPath(home))
-}
-
-func loadManifestAt(path string) (*manifest, error) {
- data, err := os.ReadFile(path)
+ data, err := os.ReadFile(manifestPath(home))
if errors.Is(err, os.ErrNotExist) {
return &manifest{SchemaVersion: manifestSchemaVersion}, nil
}
@@ -73,10 +67,10 @@ func loadManifestAt(path string) (*manifest, error) {
}
var m manifest
if err := json.Unmarshal(data, &m); err != nil {
- return nil, fmt.Errorf("%s is not valid JSON: %w", path, err)
+ return nil, fmt.Errorf("%s is not valid JSON: %w", manifestPath(home), err)
}
if m.SchemaVersion != manifestSchemaVersion {
- return nil, fmt.Errorf("%s has schema version %d; this Beacon understands %d", path, m.SchemaVersion, manifestSchemaVersion)
+ return nil, fmt.Errorf("%s has schema version %d; this Beacon understands %d", manifestPath(home), m.SchemaVersion, manifestSchemaVersion)
}
return &m, nil
}
@@ -131,10 +125,7 @@ func (m *manifest) drop(harness, path string) {
// save writes the manifest 0600 in a 0700 directory, like the rest of ~/.beacon. An empty
// manifest is removed rather than left behind.
func (m *manifest) save(home string) error {
- return m.saveAt(manifestPath(home))
-}
-
-func (m *manifest) saveAt(path string) error {
+ path := manifestPath(home)
if len(m.Records) == 0 {
err := os.Remove(path)
if errors.Is(err, os.ErrNotExist) {
diff --git a/cli/beacon/internal/mcpconnect/targets.go b/cli/beacon/internal/mcpconnect/targets.go
index 751f9bff..d4bbda5c 100644
--- a/cli/beacon/internal/mcpconnect/targets.go
+++ b/cli/beacon/internal/mcpconnect/targets.go
@@ -61,8 +61,6 @@ type Target struct {
path func(home string) (string, error)
container []string // path to the object holding servers, e.g. ["mcpServers"]
entry func(url, tokenEnv string) ordered
- // localEntry is the entry for the local stdio server `beacon mcp serve`, run by command.
- localEntry func(command string) ordered
// skeleton is the content of a config Beacon creates, besides the server entry.
skeleton ordered
// cli names a CLI whose own `mcp add`/`mcp remove` Beacon prefers when it is on PATH.
@@ -91,9 +89,6 @@ func Targets() []Target {
}
return e
},
- localEntry: func(command string) ordered {
- return ordered{{"type", "stdio"}, {"command", command}, {"args", localArgs()}}
- },
oauthNext: "In Claude Code, run /mcp, choose " + ServerName + ", and sign in.",
tokenNext: "Set %s in the environment Claude Code starts from.",
},
@@ -107,9 +102,6 @@ func Targets() []Target {
}
return e
},
- localEntry: func(command string) ordered {
- return ordered{{"command", command}, {"args", localArgs()}}
- },
oauthNext: "Run `codex mcp login " + ServerName + "`.",
tokenNext: "Set %s in the environment Codex starts from.",
},
@@ -123,9 +115,6 @@ func Targets() []Target {
}
return e
},
- localEntry: func(command string) ordered {
- return ordered{{"command", command}, {"args", localArgs()}}
- },
oauthNext: "In Cursor Settings → MCP, find " + ServerName + " (marked \"Needs login\") and sign in.",
tokenNext: "Set %s in the environment Cursor starts from.",
},
@@ -140,9 +129,6 @@ func Targets() []Target {
}
return e
},
- localEntry: func(command string) ordered {
- return ordered{{"type", "stdio"}, {"command", command}, {"args", localArgs()}}
- },
oauthNext: "In VS Code, run \"MCP: List Servers\", start " + ServerName + ", and sign in.",
tokenNext: "VS Code asks for the token the first time " + ServerName + " starts and keeps it in its secret storage; it does not read %s.",
},
@@ -156,9 +142,6 @@ func Targets() []Target {
}
return e
},
- localEntry: func(command string) ordered {
- return ordered{{"command", command}, {"args", localArgs()}}
- },
oauthNext: "In Gemini CLI, run /mcp auth " + ServerName + ". Gemini CLI loads MCP servers only in trusted folders.",
tokenNext: "Set %s in the environment Gemini CLI starts from. Gemini CLI loads MCP servers only in trusted folders.",
},
@@ -173,9 +156,6 @@ func Targets() []Target {
}
return e
},
- localEntry: func(command string) ordered {
- return ordered{{"type", "local"}, {"command", append([]any{command}, localArgs()...)}, {"enabled", true}}
- },
oauthNext: "Run `opencode mcp auth " + ServerName + "`.",
tokenNext: "Set %s in the environment OpenCode starts from.",
},
diff --git a/cli/beacon/internal/mcpconnect/tomledit.go b/cli/beacon/internal/mcpconnect/tomledit.go
index e9b5b5c1..fd996dde 100644
--- a/cli/beacon/internal/mcpconnect/tomledit.go
+++ b/cli/beacon/internal/mcpconnect/tomledit.go
@@ -45,23 +45,11 @@ func tomlBlock(table string, name string, fields []field, eol string) string {
var b strings.Builder
b.WriteString("[" + table + "." + tomlKey(name) + "]" + eol)
for _, f := range fields {
- b.WriteString(f.Key + " = " + tomlValue(f.Value) + eol)
+ b.WriteString(f.Key + " = " + tomlString(fmt.Sprint(f.Value)) + eol)
}
return b.String()
}
-// tomlValue renders a string, or an array of strings, the way `codex mcp add` writes them.
-func tomlValue(value any) string {
- if list, ok := value.([]any); ok {
- parts := make([]string, len(list))
- for i, v := range list {
- parts[i] = tomlString(fmt.Sprint(v))
- }
- return "[" + strings.Join(parts, ", ") + "]"
- }
- return tomlString(fmt.Sprint(value))
-}
-
var bareTOMLKey = regexp.MustCompile(`^[A-Za-z0-9_-]+$`)
func tomlKey(name string) string {
diff --git a/cli/beacon/internal/onboarding/profile.go b/cli/beacon/internal/onboarding/profile.go
index 46815a25..85dce1b8 100644
--- a/cli/beacon/internal/onboarding/profile.go
+++ b/cli/beacon/internal/onboarding/profile.go
@@ -78,9 +78,10 @@ type Onboarding struct {
Destination string `json:"destination,omitempty"`
// PrivacyMode applies only to Beacon Cloud forwarding.
PrivacyMode string `json:"privacy_mode,omitempty"`
- // MCPServer and AgentSkills record the agent tools answer: "installed" when the person
+ // CloudMCP and AgentSkills record the agent tools answer: "installed" when the person
// kept the tool selected, "declined" when they turned it off, empty when never asked.
- MCPServer string `json:"mcp_server,omitempty"`
+ // CloudMCP is asked only with the Beacon Cloud destination.
+ CloudMCP string `json:"cloud_mcp,omitempty"`
AgentSkills string `json:"agent_skills,omitempty"`
}
diff --git a/cli/beacon/internal/onboarding/wizard.go b/cli/beacon/internal/onboarding/wizard.go
index ead1f5b3..107bd5a4 100644
--- a/cli/beacon/internal/onboarding/wizard.go
+++ b/cli/beacon/internal/onboarding/wizard.go
@@ -60,8 +60,9 @@ type WizardOptions struct {
DestinationOnly bool
PresetDestination string
PresetPrivacyMode string
- // OfferAgentTools adds the agent tools screen before confirm, whichever destination is
- // chosen. Both tools start selected: turning one off is the person's choice to make.
+ // OfferAgentTools adds the agent tools screen before confirm. The Beacon agent skills are
+ // offered whichever destination is chosen; Beacon Cloud MCP only with Beacon Cloud. Every
+ // offered tool starts selected: turning one off is the person's choice to make.
OfferAgentTools bool
// SignIn signs in in place. When nil the wizard keeps its original contract:
@@ -93,10 +94,11 @@ type WizardResult struct {
// nothing to authorize it.
WithoutAccount bool
- // InstallMCP and InstallSkills are the agent tools the person kept selected. Both are
- // false when the screen was not offered.
- InstallMCP bool
- InstallSkills bool
+ // ConnectCloudMCP and InstallSkills are the agent tools the person kept selected. Both are
+ // false when the screen was not offered, and ConnectCloudMCP is false unless the
+ // destination is Beacon Cloud.
+ ConnectCloudMCP bool
+ InstallSkills bool
}
type wizardScreen int
@@ -113,11 +115,10 @@ const (
confirmScreen
)
-// Rows of the agent tools screen.
+// Agent tools the wizard can offer.
const (
- agentToolMCP = iota
+ agentToolCloudMCP = iota
agentToolSkills
- agentToolCount
)
type wizardModel struct {
@@ -206,10 +207,10 @@ var (
func newWizardModel(options WizardOptions) wizardModel {
screen := welcomeScreen
result := WizardResult{
- Destination: options.PresetDestination,
- PrivacyMode: options.PresetPrivacyMode,
- InstallMCP: options.OfferAgentTools,
- InstallSkills: options.OfferAgentTools,
+ Destination: options.PresetDestination,
+ PrivacyMode: options.PresetPrivacyMode,
+ ConnectCloudMCP: options.OfferAgentTools,
+ InstallSkills: options.OfferAgentTools,
}
needSignIn := false
if options.DestinationOnly {
@@ -328,10 +329,22 @@ func (m wizardModel) isPicker() bool {
return m.screen == destinationScreen || m.screen == privacyScreen || m.screen == signInFailedScreen || m.screen == agentToolsScreen
}
+// agentTools are the rows of the agent tools screen, in order.
+func (m wizardModel) agentTools() []int {
+ if m.result.Destination == DestinationAsymptote {
+ return []int{agentToolCloudMCP, agentToolSkills}
+ }
+ return []int{agentToolSkills}
+}
+
func (m *wizardModel) toggleAgentTool() {
- switch m.selected {
- case agentToolMCP:
- m.result.InstallMCP = !m.result.InstallMCP
+ tools := m.agentTools()
+ if m.selected < 0 || m.selected >= len(tools) {
+ return
+ }
+ switch tools[m.selected] {
+ case agentToolCloudMCP:
+ m.result.ConnectCloudMCP = !m.result.ConnectCloudMCP
case agentToolSkills:
m.result.InstallSkills = !m.result.InstallSkills
}
@@ -476,6 +489,9 @@ func (m wizardModel) advance() (tea.Model, tea.Cmd) {
case agentToolsScreen:
m.screen = confirmScreen
case confirmScreen:
+ if m.result.Destination != DestinationAsymptote {
+ m.result.ConnectCloudMCP = false
+ }
m.result.Completed = true
return m, tea.Quit
}
@@ -496,7 +512,7 @@ func (m wizardModel) choiceCount() int {
case signInFailedScreen:
return len(m.recoveryChoices())
case agentToolsScreen:
- return agentToolCount
+ return len(m.agentTools())
default:
return len(m.destinations())
}
@@ -677,12 +693,12 @@ func (m wizardModel) View() string {
body = strings.Join(rows, "\n")
case agentToolsScreen:
title = "Set up your agents"
- body = "Give your agents their own history. Both run on this machine and send nothing anywhere.\n\n"
+ body = "Give your agents their own history.\n\n"
var rows []string
- for index := 0; index < agentToolCount; index++ {
- label, detail := agentToolCopy(index)
+ for index, tool := range m.agentTools() {
+ label, detail := agentToolCopy(tool)
box := "[ ] "
- if m.agentToolOn(index) {
+ if m.agentToolOn(tool) {
box = "[x] "
}
line := " " + box + label
@@ -726,10 +742,10 @@ func (m wizardModel) View() string {
return lipgloss.NewStyle().Padding(1, 3).Render(card)
}
-func (m wizardModel) agentToolOn(index int) bool {
- switch index {
- case agentToolMCP:
- return m.result.InstallMCP
+func (m wizardModel) agentToolOn(tool int) bool {
+ switch tool {
+ case agentToolCloudMCP:
+ return m.result.ConnectCloudMCP
case agentToolSkills:
return m.result.InstallSkills
}
@@ -738,11 +754,11 @@ func (m wizardModel) agentToolOn(index int) bool {
func (m wizardModel) agentToolsSummary() string {
var on []string
- if m.result.InstallMCP {
- on = append(on, "Beacon MCP server")
- }
- if m.result.InstallSkills {
- on = append(on, "Beacon agent skills")
+ for _, tool := range m.agentTools() {
+ if m.agentToolOn(tool) {
+ label, _ := agentToolCopy(tool)
+ on = append(on, label)
+ }
}
if len(on) == 0 {
return "none"
@@ -750,15 +766,17 @@ func (m wizardModel) agentToolsSummary() string {
return strings.Join(on, ", ")
}
-func agentToolCopy(index int) (string, string) {
- if index == agentToolMCP {
- return "Beacon MCP server",
- "Registers `beacon mcp serve` with Claude Code, Codex, Cursor, VS Code, Gemini CLI and " +
- "OpenCode, so agents can search this machine's sessions."
+func agentToolCopy(tool int) (string, string) {
+ if tool == agentToolCloudMCP {
+ return "Beacon Cloud MCP",
+ "Adds Beacon Cloud MCP to Claude Code, Codex, Cursor, VS Code, Gemini CLI and OpenCode, " +
+ "so your agents can search the history this machine forwards. Each signs in with " +
+ "beacon.sh the first time; no token is written."
}
return "Beacon agent skills",
"Installs the Beacon skills for every project (~/.agents/skills, and ~/.claude/skills for " +
- "Claude Code): recall lessons from past sessions, distill new ones, and build lenses."
+ "Claude Code): recall lessons from past sessions, distill new ones, and build lenses. " +
+ "Installed on this machine; nothing is sent."
}
func destinationCopy(destination string) (string, string) {
diff --git a/cli/beacon/internal/onboarding/wizard_test.go b/cli/beacon/internal/onboarding/wizard_test.go
index 53b0f31d..1d0f8b90 100644
--- a/cli/beacon/internal/onboarding/wizard_test.go
+++ b/cli/beacon/internal/onboarding/wizard_test.go
@@ -662,67 +662,53 @@ func TestSignInScreenHonorsNoBrowser(t *testing.T) {
}
}
-func TestAgentToolsAreOfferedForEitherDestinationAndStartSelected(t *testing.T) {
- for _, destination := range []string{DestinationLocal, DestinationAsymptote} {
- model := newWizardModel(WizardOptions{
- SignedIn: true,
- Email: "[email protected]",
- OfferManaged: true,
- OfferAgentTools: true,
- })
- model.width, model.height = 100, 40
- model, _ = advanceWizard(t, model, "enter")
- if destination == DestinationLocal {
- model, _ = advanceWizard(t, model, "j")
- }
- model, _ = advanceWizard(t, model, "enter")
- if destination == DestinationAsymptote {
- model, _ = advanceWizard(t, model, "enter") // disclosure
- model, _ = advanceWizard(t, model, "enter") // privacy
- }
- if model.screen != agentToolsScreen {
- t.Fatalf("%s: screen = %v, want agent tools", destination, model.screen)
- }
- if !model.result.InstallMCP || !model.result.InstallSkills {
- t.Fatalf("%s: agent tools should start selected: %#v", destination, model.result)
- }
- view := model.View()
- for _, want := range []string{"[x] Beacon MCP server", "[x] Beacon agent skills", "space"} {
- if !strings.Contains(view, want) {
- t.Fatalf("%s: agent tools screen missing %q:\n%s", destination, want, view)
- }
- }
- model, _ = advanceWizard(t, model, "enter")
- if model.screen != confirmScreen {
- t.Fatalf("%s: screen = %v, want confirm", destination, model.screen)
- }
- if view := model.View(); !strings.Contains(view, "Agent tools: Beacon MCP server, Beacon agent skills") {
- t.Fatalf("%s: confirm screen should list the agent tools:\n%s", destination, view)
- }
- model, _ = advanceWizard(t, model, "enter")
- if !model.result.Completed || model.result.Destination != destination {
- t.Fatalf("%s: result = %#v", destination, model.result)
+func TestManagedWizardOffersCloudMCPAndSkillsSelected(t *testing.T) {
+ model := newWizardModel(WizardOptions{
+ SignedIn: true,
+ Email: "[email protected]",
+ OfferManaged: true,
+ OfferAgentTools: true,
+ })
+ model.width, model.height = 100, 40
+ model, _ = advanceWizard(t, model, "enter") // welcome
+ model, _ = advanceWizard(t, model, "enter") // Beacon Cloud
+ model, _ = advanceWizard(t, model, "enter") // disclosure
+ model, _ = advanceWizard(t, model, "enter") // privacy
+ if model.screen != agentToolsScreen {
+ t.Fatalf("screen = %v, want agent tools", model.screen)
+ }
+ view := model.View()
+ for _, want := range []string{"[x] Beacon Cloud MCP", "[x] Beacon agent skills", "space"} {
+ if !strings.Contains(view, want) {
+ t.Fatalf("agent tools screen missing %q:\n%s", want, view)
}
}
+ model, _ = advanceWizard(t, model, "enter")
+ if view := model.View(); !strings.Contains(view, "Agent tools: Beacon Cloud MCP, Beacon agent skills") {
+ t.Fatalf("confirm screen should list the agent tools:\n%s", view)
+ }
+ model, _ = advanceWizard(t, model, "enter")
+ if !model.result.Completed || !model.result.ConnectCloudMCP || !model.result.InstallSkills {
+ t.Fatalf("result = %#v", model.result)
+ }
}
-func TestAgentToolsCanBeTurnedOff(t *testing.T) {
+func TestManagedWizardCanTurnOffCloudMCP(t *testing.T) {
model := newWizardModel(WizardOptions{
SignedIn: true,
OfferManaged: true,
OfferAgentTools: true,
DestinationOnly: true,
- PresetDestination: DestinationLocal,
+ PresetDestination: DestinationAsymptote,
})
model.width, model.height = 100, 40
- if model.screen != agentToolsScreen {
- t.Fatalf("screen = %v, want agent tools", model.screen)
- }
+ model, _ = advanceWizard(t, model, "enter") // disclosure
+ model, _ = advanceWizard(t, model, "enter") // privacy
model, _ = advanceWizard(t, model, " ")
- if model.result.InstallMCP || !model.result.InstallSkills {
- t.Fatalf("space should turn off the MCP server only: %#v", model.result)
+ if model.result.ConnectCloudMCP || !model.result.InstallSkills {
+ t.Fatalf("space should turn off Beacon Cloud MCP only: %#v", model.result)
}
- if view := model.View(); !strings.Contains(view, "[ ] Beacon MCP server") {
+ if view := model.View(); !strings.Contains(view, "[ ] Beacon Cloud MCP") {
t.Fatalf("turned-off tool should render unchecked:\n%s", view)
}
model, _ = advanceWizard(t, model, "j")
@@ -732,12 +718,36 @@ func TestAgentToolsCanBeTurnedOff(t *testing.T) {
t.Fatalf("confirm should say no agent tools:\n%s", view)
}
model, _ = advanceWizard(t, model, "enter")
- if !model.result.Completed || model.result.InstallMCP || model.result.InstallSkills {
+ if !model.result.Completed || model.result.ConnectCloudMCP || model.result.InstallSkills {
+ t.Fatalf("result = %#v", model.result)
+ }
+}
+
+func TestLocalWizardOffersOnlySkills(t *testing.T) {
+ model := newWizardModel(WizardOptions{
+ SignedIn: true,
+ OfferManaged: true,
+ OfferAgentTools: true,
+ })
+ model.width, model.height = 100, 40
+ model, _ = advanceWizard(t, model, "enter") // welcome
+ model, _ = advanceWizard(t, model, "j")
+ model, _ = advanceWizard(t, model, "enter") // Local
+ if model.screen != agentToolsScreen {
+ t.Fatalf("screen = %v, want agent tools", model.screen)
+ }
+ view := model.View()
+ if strings.Contains(view, "Cloud MCP") || !strings.Contains(view, "[x] Beacon agent skills") {
+ t.Fatalf("local agent tools screen should offer only the skills:\n%s", view)
+ }
+ model, _ = advanceWizard(t, model, "enter")
+ model, _ = advanceWizard(t, model, "enter")
+ if !model.result.Completed || model.result.ConnectCloudMCP || !model.result.InstallSkills {
t.Fatalf("result = %#v", model.result)
}
}
-func TestFinishingWithoutAnAccountStillOffersAgentTools(t *testing.T) {
+func TestFinishingWithoutAnAccountStillOffersSkills(t *testing.T) {
model := newWizardModel(WizardOptions{OfferManaged: true, OfferAgentTools: true, NoDisplay: errors.New("no display")})
model.width, model.height = 100, 40
model, _ = advanceWizard(t, model, "enter")
@@ -745,14 +755,22 @@ func TestFinishingWithoutAnAccountStillOffersAgentTools(t *testing.T) {
t.Fatalf("screen = %v, want recovery", model.screen)
}
model, _ = advanceWizard(t, model, "enter") // finish without an account
- if model.screen != agentToolsScreen || !model.result.InstallMCP || !model.result.InstallSkills {
+ if model.screen != agentToolsScreen || !model.result.InstallSkills {
t.Fatalf("screen = %v result = %#v", model.screen, model.result)
}
+ if view := model.View(); strings.Contains(view, "Cloud MCP") {
+ t.Fatalf("no Cloud MCP without Beacon Cloud:\n%s", view)
+ }
+ model, _ = advanceWizard(t, model, "enter")
+ model, _ = advanceWizard(t, model, "enter")
+ if model.result.ConnectCloudMCP {
+ t.Fatalf("result = %#v", model.result)
+ }
}
func TestAgentToolsScreenIsSkippedWhenNotOffered(t *testing.T) {
model := newWizardModel(WizardOptions{SignedIn: true, OfferManaged: true, DestinationOnly: true, PresetDestination: DestinationLocal})
- if model.screen != confirmScreen || model.result.InstallMCP || model.result.InstallSkills {
+ if model.screen != confirmScreen || model.result.ConnectCloudMCP || model.result.InstallSkills {
t.Fatalf("screen = %v result = %#v", model.screen, model.result)
}
}
diff --git a/docs/cli/endpoint-onboarding.mdx b/docs/cli/endpoint-onboarding.mdx
index a68c97e7..91941e59 100644
--- a/docs/cli/endpoint-onboarding.mdx
+++ b/docs/cli/endpoint-onboarding.mdx
@@ -26,8 +26,8 @@ The first interactive `beacon endpoint install` opens a full-screen terminal wiz
usage coming soon. Local is a dashboard for this machine's telemetry,
kept for as long as the logs are on disk, with nothing leaving the machine.
3. For Beacon Cloud, choose **Standard** or **Metadata only** forwarding.
-4. Choose the agent tools to set up. Both are selected; press <kbd>space</kbd> to turn
- one off.
+4. Choose the agent tools to set up: Beacon Cloud MCP (Beacon Cloud only) and the
+ Beacon agent skills. Each is selected; press <kbd>space</kbd> to turn one off.
5. Review the destination, privacy mode and agent tools, then confirm installation.
Move between choices with the arrow keys, continue with <kbd>enter</kbd>, and cancel
@@ -94,28 +94,33 @@ a failed install leaves nothing behind and asks again next time.
## Agent tools
-Whichever destination you choose, the wizard then offers two agent tools. Both are
-selected by default, so setting them up is opt-out:
-
-- **Beacon MCP server** registers the local server, [`beacon mcp serve`](/cli/mcp-serve),
- as `beacon` in the user-level config of every detected harness Beacon can write:
- Claude Code, Codex CLI, Cursor, VS Code, Gemini CLI and OpenCode. Agents can then
- search this machine's sessions and approved memory. See
- [`beacon mcp install`](/cli/mcp-install).
-- **Beacon agent skills** installs the [Beacon Skills](/concepts/beacon-skills) for
- every project: into `~/.agents/skills`, and into `~/.claude/skills` when Claude Code
- is set up. See [`beacon skills`](/cli/skills).
-
-Both read local data only and send nothing anywhere. They are set up after the local
-install succeeds, alongside the runtime hooks; a failure is a warning that names the
-command to retry, never a failed install. An existing `beacon` MCP entry, or a skill
-directory of the same name that Beacon did not write, is left as it is.
-
-Turning a tool off writes nothing for it. The answer is recorded in the onboarding
-record as `onboarding.mcp_server` and `onboarding.agent_skills` (`installed` or
-`declined`). Set up or remove either one later with `beacon mcp install|uninstall` and
-`beacon skills install|uninstall`. Beacon Cloud MCP stays a separate, explicit step:
-[`beacon mcp connect`](/cli/mcp-connect).
+After the destination, the wizard offers agent tools. Each is selected by default, so
+setting them up is opt-out:
+
+- **Beacon Cloud MCP**, offered only when you choose Beacon Cloud, runs
+ [`beacon mcp connect`](/cli/mcp-connect) for you: it registers the Beacon Cloud MCP
+ server as `beacon-managed` in every detected harness Beacon can configure (Claude
+ Code, Codex CLI, Cursor, VS Code, Gemini CLI and OpenCode), so your agents can search
+ the history this machine forwards. It uses OAuth, so Beacon writes only the URL and
+ each harness signs in with beacon.sh the first time it connects. Leaving the row
+ selected is the confirmation `beacon mcp connect` would otherwise ask for.
+- **Beacon agent skills**, offered whichever destination you choose, installs the
+ [Beacon Skills](/concepts/beacon-skills) for every project: into `~/.agents/skills`,
+ and into `~/.claude/skills` when Claude Code is set up. See [`beacon skills`](/cli/skills).
+ This writes local files only and sends nothing.
+
+The skills are installed after the local install succeeds, alongside the runtime hooks.
+Beacon Cloud MCP is registered only once the endpoint is connected to Beacon Cloud (or
+already was): if enrollment fails, MCP is skipped too and the install says to run
+`beacon mcp connect` after `beacon endpoint connect`. Either failure is a warning that
+names the command to retry, never a failed install. A skill directory of the same name
+that Beacon did not write is left as it is, and `beacon mcp connect` leaves any
+`beacon-managed` entry it did not write alone.
+
+Turning a tool off writes nothing for it. The answers are recorded in the onboarding
+record as `onboarding.cloud_mcp` (Beacon Cloud only) and `onboarding.agent_skills`
+(`installed` or `declined`). Set up or remove either one later with
+`beacon mcp connect|disconnect` and `beacon skills install|uninstall`.
Every later `beacon endpoint install` and `beacon endpoint repair` updates the skill
copies Beacon installed to match the new binary. It never installs skills that were
diff --git a/docs/cli/mcp-connect.mdx b/docs/cli/mcp-connect.mdx
index 5044d045..c4487619 100644
--- a/docs/cli/mcp-connect.mdx
+++ b/docs/cli/mcp-connect.mdx
@@ -29,9 +29,11 @@ Beacon Cloud MCP is read-only. Its tools are `beacon_search_sessions`, `beacon_g
`beacon_read_session`, `beacon_get_event`, `beacon_lookup` and `beacon_usage`.
<Note>
- `beacon mcp connect` is an explicit, opt-in command. `beacon endpoint install` and the onboarding
- wizard never run it; after you choose Beacon Cloud in the wizard, the install only suggests it.
- It refuses to run as root, and in CI or without a terminal it runs only with `--yes`.
+ `beacon mcp connect` never runs on an unattended install. The interactive onboarding wizard runs
+ it for you after you choose Beacon Cloud, unless you turn "Beacon Cloud MCP" off on its
+ [agent tools screen](/cli/endpoint-onboarding#agent-tools); if you turn it off, the install
+ suggests it instead. It refuses to run as root, and in CI or without a terminal it runs only
+ with `--yes`.
</Note>
## `beacon mcp connect`
diff --git a/docs/cli/mcp-install.mdx b/docs/cli/mcp-install.mdx
deleted file mode 100644
index cecd1957..00000000
--- a/docs/cli/mcp-install.mdx
+++ /dev/null
@@ -1,61 +0,0 @@
----
-title: "beacon mcp install"
-description: "Register the local Beacon MCP server in your harnesses, or remove it"
----
-
-## Command overview
-
-`beacon mcp install` registers the local Beacon MCP server, [`beacon mcp serve`](/cli/mcp-serve),
-in the user-level config of every detected harness Beacon can write. `beacon mcp uninstall`
-removes the entries it wrote.
-
-```bash title="Command syntax"
-beacon mcp install [--harness NAME]...
-beacon mcp uninstall
-```
-
-The interactive [`beacon endpoint install`](/cli/endpoint-onboarding#agent-tools) runs
-`beacon mcp install` for you unless you turn the Beacon MCP server off in the wizard.
-
-The entry is named `beacon` and runs the `beacon` executable by its absolute path with
-`mcp serve`, because harnesses started from a desktop launcher do not see your shell's
-`PATH`. The server reads this machine's runtime log, so it works whether telemetry stays
-local or is also forwarded to Beacon Cloud. Nothing here touches the network.
-
-| Harness | Config |
-|---------|--------|
-| Claude Code | `~/.claude.json`, through `claude mcp add --scope user` when the `claude` CLI is on `PATH` |
-| Codex CLI | `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`) |
-| Cursor | `~/.cursor/mcp.json` |
-| VS Code | the user profile's `mcp.json` |
-| Gemini CLI | `~/.gemini/settings.json` |
-| OpenCode | `~/.config/opencode/opencode.json` or `opencode.jsonc` |
-
-Beacon adds the entry only where the name `beacon` is free. An existing `beacon` entry,
-whoever wrote it, is left as it is. Configs are edited the way
-[`beacon mcp connect`](/cli/mcp-connect) edits them: never re-serialized, backed up first,
-and parsed back to prove nothing else changed. What was written is recorded in
-`~/.beacon/mcp/local.json`.
-
-`beacon mcp uninstall` removes only the entries recorded there, and only while each one
-still runs the command Beacon wrote. An entry you have since changed is yours and stays.
-
-This is a different entry from Beacon Cloud MCP (`beacon-managed`), which
-`beacon mcp connect` manages. Neither command touches the other's entry.
-
-## Flags
-
-| Flag | Description |
-|------|-------------|
-| `--harness NAME` | Harness to configure (repeatable). Defaults to every detected harness |
-
-## Related
-
-<Columns cols={2}>
- <Card title="beacon mcp serve" icon="server" href="/cli/mcp-serve">
- The local server the entry runs.
- </Card>
- <Card title="beacon skills" icon="book" href="/cli/skills">
- Install the Beacon Skills for every project.
- </Card>
-</Columns>
diff --git a/docs/cli/skills.mdx b/docs/cli/skills.mdx
index 0513e24e..5d31b08c 100644
--- a/docs/cli/skills.mdx
+++ b/docs/cli/skills.mdx
@@ -43,7 +43,7 @@ twice: once from the plugin and once from the user-level directory. Remove one c
<Card title="Beacon Skills" icon="book" href="/concepts/beacon-skills">
What each skill does and how to use it.
</Card>
- <Card title="beacon mcp install" icon="server" href="/cli/mcp-install">
- Register the local Beacon MCP server.
+ <Card title="Endpoint onboarding" icon="wand-magic-sparkles" href="/cli/endpoint-onboarding#agent-tools">
+ The wizard step that installs the skills.
</Card>
</Columns>
diff --git a/docs/concepts/beacon-skills.mdx b/docs/concepts/beacon-skills.mdx
index 921c1304..bf4ce646 100644
--- a/docs/concepts/beacon-skills.mdx
+++ b/docs/concepts/beacon-skills.mdx
@@ -38,12 +38,11 @@ that accept MCP servers from plugins. When the server is available, recall uses
## Install
The interactive [`beacon endpoint install`](/cli/endpoint-onboarding#agent-tools)
-installs the skills for every project, and registers the local MCP server, unless you
-turn them off in the wizard. To do the same at any other time:
+installs the skills for every project unless you turn them off in the wizard. To do the
+same at any other time:
```bash
beacon skills install # ~/.agents/skills, and ~/.claude/skills when Claude Code is set up
-beacon mcp install # registers `beacon mcp serve` in detected harnesses
```
Beacon Skills also install from the `asymptote-labs/agent-beacon` repository. Most harnesses
diff --git a/docs/docs.json b/docs/docs.json
index 0de9d331..2e6120c9 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -334,7 +334,6 @@
"pages": [
"cli/mcp-serve",
"cli/mcp-doctor",
- "cli/mcp-install",
"cli/mcp-connect"
]
},