Skip to main content
Beacon Managed MCP lets an assistant search and read the agent history you forward to Beacon Managed. Use it to find a past session, recover a command or tool result, revisit work across different harnesses, and inspect token usage without leaving your current agent. The server is read-only. It cannot change endpoint configuration, edit a session, or run a tool on your machine.

​
Before you connect

You need:
  • Beacon installed and connected to Beacon Managed
  • At least one supported MCP client on the machine
  • A Beacon account with access to the forwarded history
Connecting an endpoint and connecting MCP are separate choices. Endpoint onboarding does not add an MCP server to your harnesses.

​
Connect your agents

Run:
Beacon discovers supported harnesses, shows every configuration change it plans to make, and asks before writing. Each changed file is backed up first. The server appears as beacon-managed. By default, Beacon writes only the server URL. Each harness asks you to sign in with OAuth the first time it connects.
After connecting, restart any harness that is already running. Then sign in from that harness:
  • Claude Code: Run /mcp and choose beacon-managed.
  • Codex CLI: Run codex mcp login beacon-managed.
  • Cursor: Open Cursor Settings → MCP, find beacon-managed, and sign in.
  • VS Code: Run MCP: List Servers and start beacon-managed.
  • Gemini CLI: Run /mcp auth beacon-managed.
  • OpenCode: Run opencode mcp auth beacon-managed.
For supported configuration formats, manual setup for other harnesses, and all command flags, see the beacon mcp connect reference.

​
What your agent can do

Beacon Managed MCP exposes tools for:
  • searching sessions by text and structured filters
  • grepping retained prompts, responses, commands, tool calls, and results
  • reading a session timeline
  • retrieving one event by identifier
  • looking up related history
  • reviewing token usage
Try prompts such as:
  • “Find the session where I fixed the release workflow last week.”
  • “Show me the command that resolved the failing Go test.”
  • “Search my Claude Code and Cursor history for changes to the MCP connection flow.”
  • “Summarize token usage for this repository over the past seven days.”
Results are limited to history your account can access in Beacon Managed.

​
Privacy and retention

MCP can return only what the endpoint forwarded.
  • Standard mode sends locally retained content, including prompts, responses, tool arguments and results, subject to Beacon’s redaction and size limits.
  • Metadata-only mode removes prompts, responses, reasoning, tool arguments and results, command output, diffs, and inventory content before upload. Content search and session reading are therefore limited in this mode.
Beacon caps each retained string at 4 KB before writing it locally. Text beyond that limit is not available to Beacon Managed MCP. See Beacon Managed forwarding and retention and redaction for the complete data flow.

​
Authentication options

OAuth is the recommended default. Beacon writes no secret into harness configuration, and you approve access in the browser. If a harness cannot use MCP OAuth, create a personal MCP token and keep it in an environment variable:
Beacon writes only the environment variable reference, never the token value. Tokens can be revoked from beacon.sh → Dashboard → MCP Access.

​
Check or remove the connection

status reports which harnesses are configured and can verify the server URL. disconnect removes only entries previously written by Beacon; it leaves MCP entries you created yourself untouched.

​
Beacon Managed and local MCP

Beacon offers two separate MCP servers: Use both if you want cross-device managed history and direct access to this machine’s local data.

Beacon Managed

Learn about hosted storage, search, analytics, and long-term agent history.

beacon mcp connect

Review every command, flag, supported harness, and configuration format.

Beacon Managed forwarding

Understand what leaves an endpoint and how forwarding works.

Local Beacon MCP

Search the runtime log and approved memory stored on this machine.