beacon mcp doctor

Validate local Beacon MCP setup

Command Overview

beacon mcp doctor validates local Beacon MCP setup before you connect an MCP client.

Command syntax

beacon mcp doctor

Doctor resolves the effective runtime log path, checks transport settings, samples readable events and archives, and confirms that the expected MCP tools are registered.

Checks

Doctor reports:

• MCP transport
• Loopback HTTP address and bind check, when --transport http is used
• Runtime log path and source
• Runtime log warnings, when present
• Content handling and readable event samples
• Sampled event count
• Malformed line count
• Readable runtime archives
• Registered MCP tools

If the runtime log does not exist yet, doctor reports that Beacon MCP can still start, but activity answers will be empty until endpoint telemetry writes events.

Flags

Flag	Description
--user	Use per-user endpoint paths. Enabled by default
--system	Use system endpoint paths
--log-path PATH	Runtime JSONL log path
--transport stdio|http	MCP transport. Defaults to stdio
--addr ADDR	Loopback HTTP JSON-RPC listen address for --transport http. Defaults to 127.0.0.1:8766

Examples

Validate stdio MCP setup:

Validate stdio MCP setup

beacon mcp doctor

Validate loopback HTTP setup:

Validate loopback HTTP setup

beacon mcp doctor --transport http --addr 127.0.0.1:8766

Validate a specific runtime log:

Validate a specific runtime log

beacon mcp doctor --log-path /path/to/runtime.jsonl

Validate system-mode paths:

Validate system-mode paths

sudo beacon mcp doctor --system

Related

beacon mcp

Review MCP tools, filters, and command group behavior.

beacon mcp serve

Run the local Beacon MCP server after validation.

Test MCP Access

Understand Beacon MCP and test local client access.

Connect Cursor and Claude Code

Install Beacon MCP in local assistant clients.