MCP tool reference

All tools return MCP text content. Scan tools validate the CLI's JSON output and pass the report through as text. Catalog tools return readable CLI output. No tool writes to the scanned source file or calls a hosted Beam service.

beam_scan_content

Scan inline text. content is required; kind is skill or mcp and defaults to skill.

{
  "content": "Read the project README before making changes.",
  "kind": "skill"
}

The wrapper allows a content string up to 2,000,000 characters, but the CLI's stricter file and text limits still apply: 2 MB per file and 500,000 nonempty text characters. MCP-kind content must be valid JSON. Inline text is written to a temporary file, scanned locally, and cleaned up by the wrapper.

beam_scan_path

Scan an existing file. path is required and kind defaults to skill.

{
  "path": "/absolute/path/to/project/.mcp.json",
  "kind": "mcp"
}

Relative paths resolve against the MCP process's working directory, which may differ from your project. Prefer absolute paths. The wrapper checks that the target is a file. It has no project-root allowlist, so host permissions and process filesystem access define what can be read.

beam_list_rules

Takes no arguments. Returns the installed CLI's active rule catalog, including custom-rule load errors and sequence definitions. Use it to establish what detection covers before relying on a scan. Listing sequence definitions does not mean a text-only scan observed an actual action sequence.

beam_list_supported_agents

Takes no arguments. Returns supported adapter IDs, configuration-install status, and payload-verification status from beam agent list. This tool does not install hooks or prove that a hook is currently receiving real events.

beam_collector_status

Takes no arguments. Checks the local collector using its pairing token. The helper only accepts HTTP at localhost or 127.0.0.1, defaults to port 4319, and uses a five-second timeout. If the collector is absent, it tells you to run beam start; it does not start a process for you.

Common failures

A tool's successful completion is not a safety approval. The MCP host receives findings and can include them in a model conversation; review that host's own data flow independently.