beam-mcp
# beam-mcp
An [MCP](https://modelcontextprotocol.io) server that exposes [Beam](https://github.com/whyashthakker/beam-cli)'s local, offline risk-scanning to any MCP-compatible host (Claude Desktop, Claude Code, and others).
Beam observes AI agent activity and heuristically flags risky patterns (secrets, destructive commands, exfiltration, unpinned MCP dependencies, etc.) — it never executes, blocks, or approves anything. This server is a thin, read-only wrapper around the [`beam` CLI](https://github.com/whyashthakker/beam-cli): it doesn't reimplement Beam's detection logic, and it doesn't add any capability the CLI doesn't already have.
## Prerequisites
- [Beam CLI](https://github.com/whyashthakker/beam-cli) installed and on `PATH` (`npm install -g beam`).
- Node.js >= 20.17.
## Install & run
```bash
npm install
npm run build
```
Point your MCP host at the built binary over **stdio** (the only transport this server supports today):
```json
{
"mcpServers": {
"beam": {
"command": "node",
"args": ["/absolute/path/to/beam-mcp/dist/index.js"]
}
}
}
```
Or, once published: `npx beam-mcp`.
## Status
We're still building out the MCP layer for Beam. This first slice is intentionally narrow — local, read-only tools. A hosted version will be available at **mcp.agentbeam.com**.
## Tools
All tools are read-only. None of them start, stop, configure, or send data anywhere beyond your own machine (and your own already-running Beam collector, for the one tool that talks to it).
**Read tools** (any connection)
| Tool | What it does |
|---|---|
| `beam_whoami` | Signed-in user, workspace, role and permissions. |
| `beam_briefing` | "What needs attention": open and new risks by severity, top rules, agents and people, most flagged sessions, pending approvals, policy mode. Window 24h, 7d or 30d. |
| `beam_false_detections` | Rules reviewers keep dismissing, with dismiss rate and example findings: the likeliest false positives. |
| `beam_dashboard_link` | A clickable link to any dashboard page, for things without a tool (members, devices, usage, billing...). |
| `beam_audit_log` | **Link only.** Audit logs are not readable through assistants; this returns the dashboard link. |
| `beam_get_policy` | Effective policy for you, a member, or the workspace default. |
| `beam_get_policy_history` | Recent workspace policy versions and who published them. |
| `beam_list_risks` / `beam_get_risk` | Risk findings, and one finding explained in plain English. |
| `beam_list_sessions` / `beam_get_session` | Agent sessions, and the facts needed to summarize one. |
| `beam_list_approvals` | Pending or resolved agent permission requests. |
**Write tools** (only on a Read-and-write connection)
| Tool | What it does |
|---|---|
| `beam_set_policy_mode` | observe / advisory / enforce. |
| `beam_set_tool_blocked`, `beam_set_agent_disabled` | Block a tool or disable an agent, workspace-wide or for one person. |
| `beam_set_policy_rule` | Add, replace or remove a custom rule. |
| `beam_rollback_policy` | Republish an earlier policy version as a new one. |
| `beam_mark_risk` | Accept a risk, mark it a false positive (optionally dismissing repeats), block it with a policy, suspend the agent, or mark it reviewed or reopen it. |
| `beam_resolve_approval` | Approve (10-60 min) or deny an agent request. |
Every write is a preview first: the tool changes nothing until it is called again with `confirm: true`. A write
goes through only if **all** of these hold, each checked by the dashboard on every call:
1. the connection was approved with **Read and write** (token scope `mcp:write`);
2. the person is a workspace **Owner or Admin**, and still has the underlying permission;
3. an Owner has switched on **AI assistant changes** in Dashboard → Workspace (off by default, and the emergency off switch);
4. it is within the write rate limit.
Applied changes are recorded in the audit log as made through an AI assistant, naming the app.
Read results include a `url` for each item so the person can click through to it in the dashboard.
The local scanning tools above are stdio-only and are not exposed remotely.
## Security
Security is a core design constraint of this server, not an afterthought — it runs locally, exposes read-only tools only, and takes a conservative approach to anything touching your machine or the Beam collector. See [SECURITY.md](./SECURITY.md) to report a concern.
## Development
```bash
npm run dev # run src/index.ts directly with tsx
npm run typecheck
```
## License
AGPL-3.0-only — see [LICENSE](./LICENSE). Same license as [beam-cli](https://github.com/whyashthakker/beam-cli), for the same reason: this stays free and open, including for anyone who modifies it and offers it as a hosted service.
## Related
- [beam-cli](https://github.com/whyashthakker/beam-cli) — the CLI and SDK this server wraps. Open source.
TDQS
Scored across 5 tools
Each tool targets a clearly distinct operation: scanning inline content, scanning a file, listing rules, listing supported agents, and checking collector status. There is no meaningful overlap or ambiguity between them.
All tools share a consistent beam_ prefix and most follow a verb_noun pattern (scan_content, scan_path, list_rules, list_supported_agents). beam_collector_status is a minor deviation since it uses a noun phrase rather than an explicit verb, but it remains predictable.
Five tools is well-scoped for a focused read-only security scanning utility. Each tool earns its place and there is no bloat or redundancy.
The tool surface covers the core read-only workflow: scanning content or paths, understanding available detection rules, knowing which agents are supported, and checking collector health. Since the server is explicitly read-only, there are no obvious missing operations.