Skip to main content

​
Command overview

The beacon mcp command group exposes local Beacon endpoint activity and approved project memory to MCP clients. An assistant can search, summarize, and retrieve compact event records from the local runtime.jsonl log, then retrieve reviewed memory that was explicitly approved through beacon memory.
Command syntax
The server reads the same local runtime log used by the dashboard and the local memory.db store next to the endpoint log base directory. It supports stdio for desktop MCP clients and loopback HTTP JSON-RPC for local tools that connect to a running server.

​
Local and Beacon Cloud servers

Beacon has two MCP servers, registered under different names so that neither entry overwrites the other: beacon mcp connect registers beacon-managed in Claude Code, Codex CLI, Cursor, VS Code, Gemini CLI, OpenCode and Oh My Pi. By default it writes only the URL, and each harness signs in with OAuth. With --token-env, the config instead references a personal token, created with beacon mcp token create or at Dashboard → Identity → MCP Access and held in an environment variable. For other harnesses it prints the steps to add the server by hand.

​
Commands

beacon mcp serve

Run the local Beacon MCP server.

beacon mcp doctor

Validate local Beacon MCP setup and print client configuration.

beacon mcp connect

Register Beacon Cloud MCP in every harness, and remove or inspect it with disconnect and status.

​
MCP tools

The local beacon server exposes these MCP tools: Search and summary tools accept filters such as since, until, limit, q, harness, model, action, severity, category, repository, session, file, command, mcp, approval, decision, policy, review, and wazuh_level. Memory tools read approved project memory only. They do not run Jev, approve candidates, install Agent Skills, or expose pending/rejected candidates. Use project_id or the MCP client’s project context when a client needs memory for a specific repository. A project path sent by a client is matched against the projects the memory store already holds records for; Beacon does not read git metadata from a path a client supplies, so an unrecognized path returns nothing rather than widening the search.

​
Flags

These flags apply to serve and doctor. For the flags of connect, disconnect and status, see beacon mcp connect.
beacon mcp serve and beacon mcp doctor only read local Beacon runtime logs and approved local memory. They do not require a Beacon account, and HTTP transport should remain bound to loopback. beacon mcp connect is the one beacon mcp command that makes a network request: an opt-in check of the Beacon Cloud MCP URL before it writes harness configs.

beacon mcp serve

Run the local Beacon MCP server.

beacon mcp doctor

Validate local Beacon MCP setup.

beacon mcp connect

Register Beacon Cloud MCP in your harnesses.

Connect Cursor and Claude Code

Install Beacon MCP in local assistant clients.

Dashboard

Inspect the same local activity log in a browser.

Endpoint event schema

Review the normalized JSONL fields behind MCP activity results.