# MCP tool reference

> Inputs, outputs, and operational limits for all five Beam MCP tools.

Source: https://docs.agentbeam.com/agent-cli/mcp/tools

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`.

```json
{
  "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`.

```json
{
  "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

| Failure                            | Check                                                                             |
| ---------------------------------- | --------------------------------------------------------------------------------- |
| CLI executable missing             | Host PATH or the `BEAM_BIN` absolute path                                         |
| File missing                       | Absolute path and permissions of the MCP process                                  |
| Invalid MCP JSON                   | Use valid JSON, not comments or a JavaScript object literal                       |
| Input too large                    | The CLI's stricter limits as well as the wrapper schema                           |
| Subprocess timeout/output overflow | 15-second timeout and 5 MiB output buffer                                         |
| Collector token missing            | `BEAM_TOKEN` or `$BEAM_HOME/data/token`; custom data paths need explicit handling |

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.