The beacon-mcp server exposes the beacon log analytics platform's REST API as MCP tools and resources, enabling AI agents to query and analyze AI-assistant usage data. Capabilities include:
Organization & Configuration
list_organizations — Discover all available beacon organizations/tenants
health_check — Verify API reachability and org health
get_config — Read public dashboard configuration (model pricing, session thresholds)
Dashboard Access
get_dashboard — Fetch the full dashboard payload or a specific sub-section (metrics, activity, traffic, distributions, sessions, projects) with filters by date range, user, model, project, and event status
Usage Summaries (5 dimensions)
query_project_summary — Daily token/event rollup by project
query_language_summary — Daily rollup by programming language (from session detection)
query_prompt_style_summary — Daily rollup by prompt style/classification
query_employee_hourly_summary — Per-user, per-hour usage broken down by tool and model
query_session_summary — Per-session rollup identifying heaviest sessions
Raw Events & Session Drilldown
query_events — Query raw events with flexible filters and pagination (up to 500 rows, or all rows)
get_session_events — Fetch the complete event chain for a single session (prompts, token usage, errors, model)
Cacheable Resources: Static URIs beacon://orgs, beacon://config, and beacon://dashboard for client-side caching.
Additional Features
Most tools support common filters: org, from/to, project, model, user, and status (errors_only / success_only)
Flexible transport: stdio (default, for local agents like Claude Desktop/Cursor) or HTTP+SSE (--http, for remote agents)
Strong typing via Zod validation at the protocol boundary
Dual output: each tool returns both a Markdown summary and raw JSON payload
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@beacon-mcp show the dashboard summary for this month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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: logbook-mcp
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-serverThe -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.
npm install (long-lived install)npm install -g @beacon/mcp-server
# or, locally inside a project:
npm install @beacon/mcp-serverThen run with the beacon-mcp binary:
BEACON_BASE_URL=http://127.0.0.1:8080 \
BEACON_ORG=default \
beacon-mcpgit 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/.
Command | What it does | When to use |
| stdio transport (JSON-RPC over stdin/stdout) | Claude Desktop / Cursor / Cline / VS Code / Continue |
| HTTP+SSE transport | Remote agents or browser-based MCP clients |
| Print CLI usage and exit | Sanity check |
| stdio via | Developing the server itself |
| HTTP+SSE via | Developing the server itself |
| Production stdio from compiled | Verifying the published binary locally |
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 helpAll settings come from environment variables. See .env.example for the full list.
Variable | Default | Description |
|
| Beacon REST API base URL |
|
| Default organisation ID; tools can override per-call via the |
|
| Per-request timeout in milliseconds |
| (unset) | Optional bearer token (sent as |
| (unset) | Optional HTTP proxy for requests to |
|
| HTTP transport host (only with |
|
| HTTP transport port (only with |
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.
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"
}
}
}
}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"
}
}
}
}Open the Cline panel → MCP Servers → "Configure MCP Servers". Same JSON shape.
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"
}
}
]After npx -y @beacon/mcp-server --http --host 0.0.0.0 --port 8765, the endpoint is:
http://<host>:8765/mcpUse 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-stoppedTool | Description |
| List all beacon orgs available via the configured API. |
| Probe |
| Read public dashboard config (model pricing, min session event count). |
Tool | Description |
| Fetch the full dashboard payload, or a single sub-section ( |
Tool | Description |
| Daily per-project token/event rollup. |
| Daily per-language rollup (from session detection). |
| Daily per-prompt-style rollup. |
| Per-user, per-hour breakdown by tool and model. |
| Per-session rollup (heaviest sessions, models, timestamps). |
Tool | Description |
| Raw event query with |
| Fetch the full event chain for a single session, given |
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).
URI | Description |
| List of organisations (cacheable). |
| Default org's dashboard config. |
| Full default-org dashboard payload. |
For per-org resources, call the get_config / get_dashboard tools with the org argument.
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":"..."}}$BEACON_ORG (or the org argument) is not registered in the beacon API. Run list_organizations first to see what's available.
BEACON_TIMEOUT_MS is too low for the query. Try increasing it (default 30s) or narrowing the date range / using section on get_dashboard.
Check the config file path is correct.
Run the command from a terminal first to surface any error output:
npx -y @beacon/mcp-serverFully quit and re-open Claude Desktop (config changes do not hot-reload).
On macOS, look at the Claude Desktop log: ~/Library/Logs/Claude/mcp*.log.
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.
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.
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.
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:watchsrc/
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 transportPick or create a file under src/tools/.
Write a registerXxxTools(server: McpServer, client: BeaconClient): void function.
Use the shared zod schemas in filters.ts for inputs.
Format output with resultBlocks(summary, payload) from formatting.ts.
Wire the registration into server.ts.
Add a test in tests/tools.test.ts that mocks the beacon response with msw.
# Bump version
npm version patch # or minor / major
# Publish (the `prepare` script auto-runs `tsc` before upload)
npm login
npm publish --access publicThe published tarball contains only dist/, README.md, LICENSE, and package.json (controlled by package.json#files and .npmignore).
MIT — see LICENSE.
Read the public beacon configuration for an org (min session event count, model pricing).
| Name | Required | Description | Default |
|---|---|---|---|
| org | No | Organization to read config for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the read-only nature ('Read'), the type of config ('public beacon'), and specific contents ('min session event count, model pricing'). It does not mention side effects, auth, or rate limits, but for a simple read operation this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no redundant words. It front-loads the key information and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with one parameter (100% schema coverage) and no output schema, the description adequately explains the purpose and the type of data returned. It is complete for an agent to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with one param 'org' described as 'Organization to read config for.' The description adds value by specifying that the config is for an org and what data it contains, going beyond the schema's basic description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and the resource 'public beacon configuration', and specifies the contents (min session event count, model pricing). It is distinct from siblings like 'get_dashboard' and 'list_organizations'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for a specific org ('for an org'), providing clear context. However, it does not explicitly state when not to use it or mention alternatives, though it is straightforward given the sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the beacon dashboard payload (or a single sub-section) for the given date range. Returns metrics, activity, traffic, prompt/distribution breakdowns, and the top projects/sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| org | No | Organization (tenant) ID. Omit to use the default org from $BEACON_ORG. | |
| from | No | Start date inclusive (YYYY-MM-DD). | |
| to | No | End date inclusive (YYYY-MM-DD). | |
| project | No | Project name to filter by (exact match). Use 'all' to disable. | |
| model | No | Model name to filter by (substring match). Use 'all' to disable. | |
| user | No | User name or id to filter by (substring match). Accepts source_user_name or source_user_id. | |
| status | No | Restrict to error or success events only. | |
| section | No | Optional sub-module. Omit to fetch the full payload. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains the operation (fetch) and return content but does not disclose side effects, permissions, rate limits, or confirm it is read-only. Adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences effectively convey the tool's purpose and output. No wasted words; front-loaded with the action and key parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description helpfully enumerates the categories of data returned (metrics, activity, traffic, etc.). It covers the main aspects of the tool, though it could hint at the structure or size of the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds little beyond what the schema already provides. It mentions 'date range' and 'sub-section' which correspond to from/to and section parameters, but no additional semantic depth.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches the beacon dashboard payload or a sub-section for a date range, listing the specific data components it returns. This distinguishes it from sibling tools like get_session_events or query_* tools which are more narrow in scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching dashboard data but does not explicitly state when to use it versus alternatives, nor does it provide exclusions or prerequisites. The context is clear but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full event chain for a single session (compact prompt previews, token usage, errors, model). Use after query_session_summary to drill into the heaviest sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| org | No | Organization (tenant) ID. Omit to use the default org from $BEACON_ORG. | |
| user | Yes | source_user_id of the session owner. | |
| session_id | Yes | Masked session id (from a previous summary/dashboard result). | |
| project | Yes | Project key associated with the session (e.g. 'beacon'). Use '-' if unknown. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It implies a read operation but does not explicitly state read-only behavior, permissions, rate limits, or side effects. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first describes function concisely, second gives usage guidance. No redundant words, front-loaded with key purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description lists return elements (prompt previews, token usage, errors, model) adequately. Usage context with sibling tool is provided. Missing full details on pagination, error handling, or format, but sufficient for a drill-down fetch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add new parameter-level detail beyond what the schema already provides; it only mentions 'single session' contextually.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Fetch' and resource 'full event chain for a single session', lists return elements (prompt previews, token usage, errors, model), and distinguishes itself from sibling 'query_session_summary' by positioning as a drill-down tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use after query_session_summary to drill into the heaviest sessions,' providing clear context and purpose, making it easy for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether the beacon API is reachable and the (optional) org is healthy.
| Name | Required | Description | Default |
|---|---|---|---|
| org | No | Organization to check. Omit to use the default org. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states it checks reachability and health, implying read-only, but doesn't clarify response format or error behavior. Adequate for a simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words. Front-loaded with action and resource. Efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with one optional param and no output schema. Description covers purpose but omits return format. However, given low complexity, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'org' with 100% schema description coverage. The description adds minimal value by echoing 'optional' but no extra semantics. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it checks beacon API reachability and optional org health. The verb 'check' and resources are specific, distinguishing it from sibling tools like get_config or query_*.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage as a health check. No explicit when-not or alternatives, but sibling list doesn't contain similar health tools, so context is clear. Could benefit from stating it is safe to call frequently.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all beacon organizations (tenants) available via the configured beacon API. Call this first if you don't know which org to query.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only states 'List all' (implying a read operation) but omits details like authentication requirements, potential size of the list, or whether results are paginated. This is insufficient for an agent to infer safe/expected behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences (20 words). The purpose is front-loaded in the first sentence, and the second adds a critical usage hint. Every word serves a purpose with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a simple list tool with no parameters and no output schema, the description provides the basic purpose and a usage hint. However, it does not describe the output format or what fields are returned, leaving the agent to infer. Given the low complexity, this is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% coverage, so the baseline is 3. The description adds no parameter information because there are none, which is acceptable. No extra meaning is needed beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'all beacon organizations (tenants)' available via the configured API. It uses a specific verb ('list') and resource ('organizations') and distinguishes from siblings by focusing on organization discovery rather than queries or configurations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises calling this tool first when the organization is unknown: 'Call this first if you don't know which org to query.' This provides clear guidance on when to use it, though it does not explicitly mention when not to use or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per-user, per-hour usage broken down by tool and model. Use to find power users, peak hours, and per-model consumption.
| Name | Required | Description | Default |
|---|---|---|---|
| org | No | Organization (tenant) ID. Omit to use the default org from $BEACON_ORG. | |
| from | No | Start date inclusive (YYYY-MM-DD). | |
| to | No | End date inclusive (YYYY-MM-DD). | |
| project | No | Project name to filter by (exact match). Use 'all' to disable. | |
| model | No | Model name to filter by (substring match). Use 'all' to disable. | |
| user | No | User name or id to filter by (substring match). Accepts source_user_name or source_user_id. | |
| status | No | Restrict to error or success events only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description lacks disclosure of important behavioral traits such as data freshness, pagination, error handling, cost implications, or what happens with missing dates. The burden is on the description, and it falls short.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the tool's purpose and followed by usage guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the output nature and use cases for a query tool with 7 optional parameters and no output schema. However, it does not describe return format, limits, or behavior when filters yield no results, leaving gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents parameters. The description adds context by explaining the output structure, but does not add parameter-specific meaning beyond what the schema provides, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns per-user, per-hour usage broken down by tool and model, and provides specific use cases (find power users, peak hours, per-model consumption), distinguishing it from sibling query tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use scenarios for when to use the tool, but does not mention when not to use or compare directly with alternatives like query_events or query_session_summary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Raw event query with date range, project/model/status/user filters and pagination. Use for inspecting individual events (errors, specific users, model behaviour, prompt previews). By default returns up to 100 rows; pass all: true to disable the limit (use sparingly).
| Name | Required | Description | Default |
|---|---|---|---|
| org | No | Organization (tenant) ID. Omit to use the default org from $BEACON_ORG. | |
| from | No | Start date inclusive (YYYY-MM-DD). | |
| to | No | End date inclusive (YYYY-MM-DD). | |
| project | No | Project name to filter by (exact match). Use 'all' to disable. | |
| model | No | Model name to filter by (substring match). Use 'all' to disable. | |
| user | No | User name or id to filter by (substring match). Accepts source_user_name or source_user_id. | |
| status | No | Restrict to error or success events only. | |
| limit | No | Max rows to return (1-500). Ignored when `all` is true. | |
| all | No | If true, return every matching row without a limit. Use carefully — may return large payloads. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the default limit (100 rows) and the 'all' flag to disable it, and warns to use sparingly. However, it lacks details on output format, authentication needs, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the purpose, and contains no fluff. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters and no output schema, the description adequately covers the main filters and pagination behavior but omits output specifics and any behavioral caveats beyond the limit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description mentions filter categories and pagination but does not add significant detail beyond what the schema already provides for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Raw event query with date range, project/model/status/user filters and pagination' and specifies it is for inspecting individual events, distinguishing it from sibling summary tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use for inspecting individual events' and lists example uses. It does not explicitly say when not to use, but the context of summary tools in siblings implies differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily rollup per programming language (from session language detection). Use to identify which languages AI assistants are most often working in.
| Name | Required | Description | Default |
|---|---|---|---|
| org | No | Organization (tenant) ID. Omit to use the default org from $BEACON_ORG. | |
| from | No | Start date inclusive (YYYY-MM-DD). | |
| to | No | End date inclusive (YYYY-MM-DD). | |
| project | No | Project name to filter by (exact match). Use 'all' to disable. | |
| model | No | Model name to filter by (substring match). Use 'all' to disable. | |
| user | No | User name or id to filter by (substring match). Accepts source_user_name or source_user_id. | |
| status | No | Restrict to error or success events only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It states it is a 'daily rollup' and derives data from 'session language detection', which implies read-only aggregation. However, it does not explicitly confirm non-destructive behavior, describe the rollup logic, or specify what data is excluded. The description is minimal but non-contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys purpose and use case without wasted words. It is appropriately concise for a tool with 7 parameters already documented in the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and 7 parameters, yet the description does not explain the return format, aggregation method, or how filters affect the output. For a summary tool, this omission leaves agents uncertain about what data they will receive. The description is too sparse to fully compensate for missing structural metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is well described in the schema. The tool description adds no additional parameter-level meaning beyond the schema. Baseline score of 3 is appropriate as the description does not duplicate or subtract value from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides a 'daily rollup per programming language' and its use case ('identify which languages AI assistants are most often working in'). It distinguishes from sibling tools like query_project_summary by focusing specifically on language detection, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage context ('identify which languages') but does not explicitly mention when not to use this tool or suggest alternatives among siblings. It is adequate but lacks exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily rollup per project: event/request counts and token usage. Use for 'which project uses the most tokens this week' questions.
| Name | Required | Description | Default |
|---|---|---|---|
| org | No | Organization (tenant) ID. Omit to use the default org from $BEACON_ORG. | |
| from | No | Start date inclusive (YYYY-MM-DD). | |
| to | No | End date inclusive (YYYY-MM-DD). | |
| project | No | Project name to filter by (exact match). Use 'all' to disable. | |
| model | No | Model name to filter by (substring match). Use 'all' to disable. | |
| user | No | User name or id to filter by (substring match). Accepts source_user_name or source_user_id. | |
| status | No | Restrict to error or success events only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It adds that results are a daily rollup and include counts and token usage, but does not disclose behavioral traits like data freshness, pagination, sorting, or how multiple projects are handled. The transparency is adequate but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the core functionality and then a usage example. Every word earns its place; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and no output schema, the description does not explain return structure or provide sample output. It covers basic purpose but leaves gaps about what the agent can expect in terms of result format or pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema; it only reiterates the project focus. No extra parameter context or examples are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides a daily rollup per project with event/request counts and token usage, and gives an example use case. It differentiates from siblings like query_language_summary by specifying 'per project', making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a concrete usage example: 'Use for 'which project uses the most tokens this week' questions.' It implicitly guides when to use this tool over others focused on different summaries, but lacks explicit when-not-to-use or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily rollup per prompt style (rule-classified). Useful for understanding how users phrase their requests.
| Name | Required | Description | Default |
|---|---|---|---|
| org | No | Organization (tenant) ID. Omit to use the default org from $BEACON_ORG. | |
| from | No | Start date inclusive (YYYY-MM-DD). | |
| to | No | End date inclusive (YYYY-MM-DD). | |
| project | No | Project name to filter by (exact match). Use 'all' to disable. | |
| model | No | Model name to filter by (substring match). Use 'all' to disable. | |
| user | No | User name or id to filter by (substring match). Accepts source_user_name or source_user_id. | |
| status | No | Restrict to error or success events only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It reveals it is a daily rollup but omits behavioral details such as data retention, auth requirements, rate limits, or what 'rule-classified' entails. This is a significant gap for a query tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose. Every word earns its place with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite good schema coverage and no required params, the tool lacks an output schema and the description does not clarify return format, pagination, or limits. For a query tool with 7 parameters, this is a noticeable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the schema; it does not explain semantics of parameters like date format, filtering behavior, or the effect of 'all' values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Daily rollup per prompt style (rule-classified)' and explains its utility as 'useful for understanding how users phrase their requests', effectively answering what the tool does and distinguishing it from sibling summary tools like query_language_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a general use case ('understanding how users phrase their requests') but does not explicitly state when to use this tool versus alternatives (e.g., query_language_summary, query_session_summary) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per-session rollup: which sessions used the most tokens, their models, timestamps, etc. Use to find the heaviest sessions before drilling in with get_session_events.
| Name | Required | Description | Default |
|---|---|---|---|
| org | No | Organization (tenant) ID. Omit to use the default org from $BEACON_ORG. | |
| from | No | Start date inclusive (YYYY-MM-DD). | |
| to | No | End date inclusive (YYYY-MM-DD). | |
| project | No | Project name to filter by (exact match). Use 'all' to disable. | |
| model | No | Model name to filter by (substring match). Use 'all' to disable. | |
| user | No | User name or id to filter by (substring match). Accepts source_user_name or source_user_id. | |
| status | No | Restrict to error or success events only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It mentions a rollup but does not specify the exact aggregation method (e.g., totals, averages), sorting order, or pagination details. The vague 'etc.' further limits transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the key purpose, and contains no irrelevant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, no output schema), the description is thin. It does not explain what 'heaviest sessions' means exactly, nor does it mention sorting or rollup granularity. It is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to repeat parameter definitions. However, it adds no extra meaning beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a per-session rollup focusing on token usage, models, and timestamps. It distinguishes from the sibling tool get_session_events by indicating it is used for initial exploration before drilling in.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool: 'Use to find the heaviest sessions before drilling in with get_session_events.' This provides clear context and an alternative, earning top marks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct aspect of the beacon API: configuration, dashboards, session details, health, organizations, and various summaries (employee, events, language, project, prompt style, sessions). There is no overlap in purpose.
Most tools follow a consistent verb_prefix pattern: get_ for specific fetches, list_ for listings, query_ for summaries. However, health_check deviates from the pattern, and get_session_events vs query_session_summary have similar domains with different prefixes.
11 tools is well-scoped for an analytics server. It covers essential operations (config, health, org listing, session detail, and multiple summary queries) without being excessive.
The tool set appears complete for read-only analytics: it covers configuration, health, organization selection, raw events with pagination, and various rollups. Missing create/update/delete tools, but those are likely out of scope for an analytics API.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server exposing the Backtest360 engine API as tools for AI agents.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/HyperBDR/beacon-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
