beacon-mcp

MCP server for the beacon log analytics platform.

Exposes beacon's REST API as Model Context Protocol tools and resources, so any MCP-compatible AI agent (Claude Desktop, Cursor, Cline, Continue, VS Code) can query and analyse AI-assistant usage data through a typed, validated interface.

The MCP server is a thin client over beacon's existing /api/v1 endpoints — it does not duplicate SQL, Parquet, or storage logic. It can run standalone, or be launched lazily by the beacon Go API and exposed through /api/v1/mcp.

Features

• 11 tools covering organisation discovery, health checks, configuration, full dashboard, dashboard sub-sections, 5 summary dimensions, raw event query, and per-session event chain.

• 3 resources (beacon://orgs, beacon://config, beacon://dashboard) for context that should be cached client-side.

• Two transports: stdio (default) for Claude Desktop / Cursor / Cline, HTTP+SSE (--http) for remote agents.

• Strict types & validation via Zod — every argument is checked at the protocol boundary.

• Unified filter arguments: org, from, to, project, model, user, status.

• Smart summaries: each tool returns a Markdown summary plus the raw JSON payload, so LLMs can both skim and re-parse.

• API integration: works against the public /api/v1 API and can be proxied by the beacon Go backend at /api/v1/mcp; auth via BEACON_API_KEY if you front beacon with a reverse proxy.

Related MCP server: CUT Clarity MCP Server

Quick start

Option A — npx (recommended, no install)

Run directly with npx from a beacon checkout or any directory:

BEACON_BASE_URL=http://127.0.0.1:8080 \
BEACON_ORG=default \
npx -y @beacon/mcp-server

The -y flag auto-confirms the install prompt. The first invocation downloads the package (~22 kB) and starts the stdio transport immediately. Subsequent invocations are instant.

Option B — npm install (long-lived install)

npm install -g @beacon/mcp-server
# or, locally inside a project:
npm install @beacon/mcp-server

Then run with the beacon-mcp binary:

BEACON_BASE_URL=http://127.0.0.1:8080 \
BEACON_ORG=default \
beacon-mcp

Option C — from source (for development)

git clone https://github.com/HyperBDR/beacon-mcp.git
cd beacon-mcp
npm install
npm run dev                # stdio, with tsx — no build step
npm run dev:http           # HTTP+SSE on $MCP_HTTP_PORT (default 8765)

npm install is only required for development. End users never compile anything — the published package ships pre-built dist/.

Running modes

CLI flags:

--http                Run HTTP+SSE transport (default: stdio)
--host <addr>         HTTP host (default: 127.0.0.1 or $MCP_HTTP_HOST)
--port <number>       HTTP port (default: 8765 or $MCP_HTTP_PORT)
--help, -h            Show this help

Configuration

All settings come from environment variables. See .env.example for the full list.

Client configuration

Below are the most common client integrations. After editing the config, fully restart the client (Claude Desktop, Cursor) so it picks up the new MCP server.

Claude Desktop

Config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

npx version (recommended, no global install):

{
  "mcpServers": {
    "beacon": {
      "command": "npx",
      "args": ["-y", "@beacon/mcp-server"],
      "env": {
        "BEACON_BASE_URL": "http://127.0.0.1:8080",
        "BEACON_ORG": "default"
      }
    }
  }
}

Globally installed version:

{
  "mcpServers": {
    "beacon": {
      "command": "beacon-mcp",
      "args": [],
      "env": {
        "BEACON_BASE_URL": "http://127.0.0.1:8080",
        "BEACON_ORG": "default"
      }
    }
  }
}

Development version (from a beacon-mcp source checkout, with npm install already run):

{
  "mcpServers": {
    "beacon-dev": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/beacon-mcp/src/index.ts"],
      "env": {
        "BEACON_BASE_URL": "http://127.0.0.1:8080",
        "BEACON_ORG": "default"
      }
    }
  }
}

Cursor

Settings → MCP → Add new global MCP server. Same JSON shape as Claude Desktop (the mcpServers map is the standard).

A typical ~/.cursor/mcp.json:

{
  "mcpServers": {
    "beacon": {
      "command": "npx",
      "args": ["-y", "@beacon/mcp-server"],
      "env": {
        "BEACON_BASE_URL": "http://127.0.0.1:8080",
        "BEACON_ORG": "default"
      }
    }
  }
}

Cline (VS Code)

Open the Cline panel → MCP Servers → "Configure MCP Servers". Same JSON shape.

Continue (VS Code JetBrains)

Add to ~/.continue/config.json under experimental.modelContextProtocolServers:

[
  {
    "name": "beacon",
    "command": "npx",
    "args": ["-y", "@beacon/mcp-server"],
    "env": {
      "BEACON_BASE_URL": "http://127.0.0.1:8080",
      "BEACON_ORG": "default"
    }
  }
]

Remote agents (HTTP+SSE)

After npx -y @beacon/mcp-server --http --host 0.0.0.0 --port 8765, the endpoint is:

http://<host>:8765/mcp

Use any MCP HTTP client (the SDK ships Python/TS/Go/Kotlin clients). CORS is open by default — set up a reverse proxy with auth in production.

The server is a long-running process. Common deployment patterns:

# systemd unit
[Service]
ExecStart=/usr/bin/env npx -y @beacon/mcp-server --http --host 0.0.0.0 --port 8765
Environment=BEACON_BASE_URL=http://beacon.internal:8080
Environment=BEACON_ORG=production
Restart=always

# docker-compose snippet
beacon-mcp:
  image: node:22-alpine
  command: ["npx", "-y", "@beacon/mcp-server", "--http", "--host", "0.0.0.0", "--port", "8765"]
  environment:
    BEACON_BASE_URL: http://beacon:8080
    BEACON_ORG: production
  ports:
    - "8765:8765"
  restart: unless-stopped

Tool reference

Org & config

Dashboard

Summary (5 dimensions)

Events & sessions

Common arguments

Almost every tool accepts:

• org — organisation ID; falls back to $BEACON_ORG.

• from / to — YYYY-MM-DD (inclusive).

• project — exact project name, or "all" to disable.

• model — substring match, or "all".

• user — substring match against source_user_name or source_user_id.

• status — "errors_only" or "success_only".

query_events additionally accepts limit (1-500, default 100) and all (boolean).

Resources

For per-org resources, call the get_config / get_dashboard tools with the org argument.

Output format

Every tool returns a single MCP content block with a Markdown summary followed by a fenced JSON payload. Example:

## Summary

### Overview
- Events: **12,480** (requests: 9,201, sessions: 318)
- Tokens: **42.1M** (prompt 30.5M + completion 11.6M)
- ...

### Top projects
| Project | Tokens | Events | Requests | Share |
| --- | --- | --- | --- | --- |
| beacon | 18,205,440 | 4,820 | 3,612 | 43.2% |
| ... |

## Data (JSON)
```json
{ "code": 0, "message": "success", "data": [...], "meta": {...} }

This dual format lets the model either skim the Markdown (low token cost) or re-parse the JSON (precise). Errors are returned as `isError: true` with a plain-text message.

---

## Troubleshooting

### "Failed to connect to 127.0.0.1 port 8080"

The beacon API isn't running, or `BEACON_BASE_URL` is wrong.

```bash
curl $BEACON_BASE_URL/api/v1/health
# expected: {"code":0,"message":"success","data":{"status":"ok","time":"..."}}

"organization "X" not found"

$BEACON_ORG (or the org argument) is not registered in the beacon API. Run list_organizations first to see what's available.

"context deadline exceeded"

BEACON_TIMEOUT_MS is too low for the query. Try increasing it (default 30s) or narrowing the date range / using section on get_dashboard.

Claude Desktop: "MCP server disconnected"

1. Check the config file path is correct.

2. Run the command from a terminal first to surface any error output:

   npx -y @beacon/mcp-server

3. Fully quit and re-open Claude Desktop (config changes do not hot-reload).

4. On macOS, look at the Claude Desktop log: ~/Library/Logs/Claude/mcp*.log.

HTTP+SSE: CORS or 401 errors

The server ships with CORS wide open for browser clients. If you front it with nginx/traefik, configure Authorization: Bearer $BEACON_API_KEY forwarding at the proxy. The MCP SDK does not enforce auth itself — protect the endpoint with a reverse-proxy in production.

Behind a corporate proxy

Set BEACON_PROXY to route beacon traffic through the proxy. This affects only the MCP server → beacon direction (not the MCP client ↔ MCP server transport). The agent that runs the MCP client (Claude Desktop, Cursor, etc.) is unaffected.

{
  "mcpServers": {
    "beacon": {
      "command": "npx",
      "args": ["-y", "@beacon/mcp-server"],
      "env": {
        "BEACON_BASE_URL": "http://beacon.internal:8080",
        "BEACON_ORG": "default",
        "BEACON_PROXY": "http://proxy.corp.local:8080"
      }
    }
  }
}

Supported schemes: http://, https://, socks5://. The socks5:// form requires Node 18+ which uses undici 5+ under the hood. If the proxy requires authentication, embed it in the URL: http://user:pass@host:port.

To verify the proxy is being used, tail the beacon server's access log while invoking any tool — requests will arrive from the proxy's IP, not the agent host.

Beacon is reachable but everything is empty

Check that the collector + analyzer pipelines have run. Raw events need to be aggregated by the analyzer before the summary endpoints return data. Run go run ./cmd/analyzer -config testdata/collector.yaml (in the beacon repo) periodically.

Development

npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest run
npm run build       # tsc → dist/ (mirrors what `npm publish` will do via the `prepare` script)

Watch mode for tests:

npm run test:watch

Layout

src/
  index.ts          # entry point, CLI parsing, transport selection
  server.ts         # McpServer construction; registers all tool modules
  client.ts         # BeaconClient — typed wrapper over beacon's REST API
  config.ts         # env + CLI arg parsing (zod-validated)
  filters.ts        # shared zod schemas (BaseFilter, EventFilter, SessionKey)
  formatting.ts     # JSON block + Markdown summary helpers
  tools/
    orgs.ts         # list_organizations, health_check, get_config + resources
    dashboard.ts    # get_dashboard + beacon://dashboard
    summary.ts      # 5 query_*_summary tools
    events.ts       # query_events
    session.ts      # get_session_events
tests/
  setup.ts          # vitest setup
  client.test.ts    # BeaconClient unit tests
  config.test.ts    # config + CLI parsing tests
  tools.test.ts     # end-to-end tool tests over an in-memory MCP transport

Adding a new tool

1. Pick or create a file under src/tools/.

2. Write a registerXxxTools(server: McpServer, client: BeaconClient): void function.

3. Use the shared zod schemas in filters.ts for inputs.

4. Format output with resultBlocks(summary, payload) from formatting.ts.

5. Wire the registration into server.ts.

6. Add a test in tests/tools.test.ts that mocks the beacon response with msw.

Publish flow

# Bump version
npm version patch   # or minor / major

# Publish (the `prepare` script auto-runs `tsc` before upload)
npm login
npm publish --access public

The published tarball contains only dist/, README.md, LICENSE, and package.json (controlled by package.json#files and .npmignore).

License

MIT — see LICENSE.