MCP server

Expose Beamd to MCP-aware agents over stdio — four tools that map straight to the CLI.

Beamd ships a Model Context Protocol server over stdio. One command, no extra install:

beamd mcp

It wraps the same background agent the CLI uses, so tunnels opened via MCP are the same detached tunnels you'd see in beamd list.

Tools

Tool	Arguments	Returns	CLI equivalent
`expose_port`	`port` (integer, 1–65535), `name?` (string)	the public HTTPS URL	`beamd open <port> --as <name>`
`remove_tunnel`	`name` (string)	`ok`	`beamd close <name>`
`list_tunnels`	—	`[{name, port, url, healthy}]`	`beamd list`
`whoami`	—	`{server, scope, slug, healthy}`	`beamd whoami`

name is an optional single label (defaults to the port). expose_port returns the URL synchronously — the agent gets a working link in one call.

Wiring it into an agent

Point any MCP client at beamd mcp over stdio. For a JSON-config client (Claude Code, Cursor, and most others):

{
  "mcpServers": {
    "beamd": {
      "command": "beamd",
      "args": ["mcp"]
    }
  }
}

The agent picks up the edge and credentials from your Beamd login (or a .beamd in the working directory), so there's nothing to configure in the MCP block itself. For a headless agent that shouldn't use your login, run it with a --config workspace key — see Embed in your app.

When to use the CLI instead

MCP is the smoothest path for MCP-aware agents. If your agent only runs shell commands, the CLI with --json is just as capable — see Use with an agent for the trade-off.