# Connect an MCP host

> Build the local server, configure a stdio entrypoint, and verify tool discovery in your assistant.

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

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

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

From your reviewed MCP checkout:

```sh
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:

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