Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.asymptotelabs.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Model Context Protocol (MCP)

Model Context Protocol (MCP) lets local assistants connect to tools and data sources through a standard interface. Beacon uses MCP to make local endpoint activity searchable from an MCP client without requiring a hosted Beacon account.

​
What it is

beacon mcp exposes compact activity tools over MCP so an assistant can search, summarize, and fetch events from the local Beacon runtime log. Beacon exposes these MCP tools:
ToolDescription
search_activitySearch local Beacon activity logs and return compact event summaries.
summarize_activitySummarize local Beacon activity over a time window and optional filters.
get_activity_eventFetch one compact event by an ID returned from search_activity.
list_activity_filtersList common filter values found in local Beacon activity logs.

​
How it works

Beacon reads the same local runtime.jsonl used by the dashboard. MCP clients can launch Beacon over stdio, or local tools can connect to a running loopback HTTP JSON-RPC server. 
beacon mcp serve
Use stdio for desktop MCP clients that launch Beacon as a subprocess. Use HTTP only for local loopback testing or local tools that connect to a running server.
Do not expose beacon mcp serve --transport http on a non-loopback interface. Beacon MCP is designed for local activity inspection, not remote administration.

​
Security use cases

MCP is useful when an analyst wants to ask a local assistant targeted questions about Beacon activity without opening the raw runtime log.
  • Find recent high-severity activity, failed tools, denied approvals, or events that need review.
  • Summarize activity by harness, model, repository, category, or MCP server over a time window.
  • Pull one event by ID and compare it with the same event in the dashboard.
  • List available filters before narrowing an investigation to a specific command, file, session, or repository.

​
How to test it

1

Write a known event

Append a synthetic endpoint event so MCP queries have a controlled record to find.
beacon endpoint test-event
2

Run MCP doctor

Confirm Beacon resolves the expected runtime log, transport, content-retention mode, and registered MCP tools.
beacon mcp doctor
3

Connect an MCP client

Follow Connect Cursor and Claude Code below, then ask the client to search recent Beacon activity or summarize activity from the last hour.
4

Test loopback HTTP if needed

If your local tool uses HTTP JSON-RPC, validate the loopback transport before connecting.
beacon mcp doctor --transport http --addr 127.0.0.1:8766
5

Compare with the dashboard

Open Log Search and confirm MCP query results match the same event window and event IDs shown by the dashboard.
beacon endpoint dashboard --open

​
Connect Cursor and Claude Code

Before connecting a client, confirm Beacon is installed and resolve the absolute CLI path: 
which beacon
beacon mcp doctor
beacon mcp doctor validates the runtime log, transport, content-retention mode, and registered MCP tools. Use the absolute path from which beacon in client configuration so the client does not depend on your shell PATH.

​
Cursor

Open or create the global Cursor MCP config: 
~/.cursor/mcp.json
Add beacon under mcpServers, merging it with any existing servers: 
{
  "mcpServers": {
    "beacon": {
      "command": "/opt/homebrew/bin/beacon",
      "args": ["mcp", "serve", "--transport", "stdio"]
    }
  }
}
Restart Cursor or run Developer: Reload Window, then verify the server in Cursor Settings → MCP. Beacon should connect with four tools: search_activity, summarize_activity, get_activity_event, and list_activity_filters.
Replace /opt/homebrew/bin/beacon with the path from which beacon. Do not rely on "command": "beacon" because Cursor’s subprocess environment may not include Homebrew or shell PATH entries.
To share the setup with a team, use .cursor/mcp.json in a repository root instead of ~/.cursor/mcp.json. The JSON shape is the same, but the server only loads for that workspace.

​
Claude Code

Use claude mcp add for the scope you want: 
# Available in all projects for your user
claude mcp add --transport stdio --scope user beacon -- /opt/homebrew/bin/beacon mcp serve --transport stdio

# Shared with a project through .mcp.json
claude mcp add --transport stdio --scope project beacon -- /opt/homebrew/bin/beacon mcp serve --transport stdio
Replace /opt/homebrew/bin/beacon with the path from which beacon. To configure Claude Code manually, add the same beacon entry to the top-level mcpServers object in ~/.claude.json for user scope or .mcp.json for project scope: 
{
  "mcpServers": {
    "beacon": {
      "command": "/opt/homebrew/bin/beacon",
      "args": ["mcp", "serve", "--transport", "stdio"]
    }
  }
}
Verify the server: 
claude mcp list
claude mcp get beacon
Inside a Claude Code session, run /mcp and confirm Beacon is connected. Project-scoped .mcp.json servers require approval the first time Claude Code loads them.

​
Troubleshooting

  • Server fails to start: use the absolute path from which beacon in command.
  • Tools connect but return empty results: run beacon endpoint status; the runtime log may not have events yet.
  • Claude Code ignores project config: approve the .mcp.json server when prompted or check project-scope MCP settings.

beacon mcp

Review MCP commands, tools, transports, and flags.

beacon mcp doctor

Validate local MCP setup and print client configuration.

Dashboard testing

Compare MCP results against the local dashboard.

Validation events

Write a known-good event before testing MCP queries.