Connect an MCP host

Use a reviewed Beam MCP checkout and an installed Beam CLI. The wrapper invokes the beam executable as a subprocess. Its README contains an older package-name example; install @agent-beam/beam, which supplies the correct executable.

Prepare the binaries

npm install -g @agent-beam/beam
beam --version

From your reviewed MCP checkout:

npm install
npm run build
npm run typecheck

The built entrypoint is dist/index.js. Keep the checkout in a stable location and use an absolute path in the host configuration. This source-based workflow does not assume the MCP package is available from a public registry.

Configure the host

For hosts using an mcpServers JSON configuration, add an entry like this while preserving existing servers:

{
  "mcpServers": {
    "beam": {
      "command": "node",
      "args": ["/absolute/path/to/agentbeam-mcp/dist/index.js"],
      "env": {
        "BEAM_BIN": "/absolute/path/to/beam"
      }
    }
  }
}

Use the actual executable path, not a shell alias. If the host cannot find Node, use its absolute path in command as well. The host decides its configuration file location and restart/discovery behavior; merge this entry into that native configuration.

Verify tool discovery

Restart or refresh the MCP host and confirm all five Beam tools appear. Invoke beam_list_rules first to verify that the wrapper can run the CLI. Then use beam_scan_content with harmless review text and inspect the returned JSON report.

Offline scanning and catalog tools do not need a collector. For beam_collector_status, run beam start separately and configure the correct loopback port and token.

Custom collector data

The MCP status helper reads BEAM_TOKEN or $BEAM_HOME/data/token. It does not currently honor BEAM_DATA_DIR for token lookup. When your collector uses another data directory, supply its token securely through the host's environment configuration, and avoid placing it in shared project files.

Troubleshoot startup

An executable-not-found error usually points to the host process's PATH, not a missing terminal installation. A JSON parse error after scanning can indicate an incompatible CLI output format. Keep wrapper and CLI releases tested together. Each CLI subprocess has a 15-second timeout and a 5 MiB output buffer; large scans can fail before results reach the host.