Skip to main content

​
Command overview

beacon mcp doctor validates local Beacon MCP setup before you connect an MCP client.
Command syntax
Doctor resolves the effective runtime log path, checks transport settings, samples readable events and archives, and confirms that the expected MCP tools are registered. Those tools cover both local activity and approved project memory.

​
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
The expected tool set is search_activity, summarize_activity, get_activity_event, list_activity_filters, search_memory, get_memory, and get_memory_context. 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.

​
Client configuration

With the stdio transport, doctor prints the client configuration for the local server, named beacon:
Local server entry
This is not the Beacon Cloud server. The session history this endpoint forwards to Beacon Cloud is served by a separate server, registered as beacon-managed by beacon mcp connect. A harness can have both entries at once, because the names differ. Doctor checks only the local server; to see where beacon-managed is configured and whether its URL answers, run beacon mcp status --check.

​
Flags

​
Examples

Validate stdio MCP setup:
Validate stdio MCP setup
Validate loopback HTTP setup:
Validate loopback HTTP setup
Validate a specific runtime log:
Validate a specific runtime log
Validate system-mode paths:
Validate system-mode paths

beacon mcp

Review MCP tools, filters, and command group behavior.

beacon mcp serve

Run the local Beacon MCP server after validation.

beacon mcp connect

Register the separate Beacon Cloud MCP server, beacon-managed.

Test MCP Access

Understand Beacon MCP and test local client access.

Connect Cursor and Claude Code

Install Beacon MCP in local assistant clients.