MCP & proposals

BEAM speaks the Model Context Protocol in both directions. mcp manages the
tool servers BEAM connects out to — Google Drive, Docs, Calendar, GitHub.
proposals is the other direction: BEAM runs an MCP server of its own, so a
client like Claude Desktop or Claude Code can be pointed at your workspace, and
this is where the writes it asks for wait for you.

The short version of the rule that matters: a connected MCP client can read
your workspace on its own. On your account, it does not change it on its own.
When it asks to add a task, edit a doc or create a list, BEAM records the request
and tells the client that nothing has changed — the change happens when you
approve it here, at whatever confirmation that command normally costs you.

Two exceptions, said plainly rather than left to be discovered. Administrator
accounts keep the old behaviour: writes from a connected client run immediately
there, and the client is told they ran. And proposals are held by the BEAM
session the client is talking to, on that one device — they are not synced, so
approving one means going back to the machine that had BEAM open.

mcp

Aliases: none
Purpose: Manage tool-server connections (Model Context Protocol).
Syntax:

>mcp
>mcp status
>mcp servers
>mcp connect <id>
>mcp disconnect <id>
>mcp tools

Flags: none
Examples:

>mcp status
>mcp tools

See also: proposals, drive, status

BEAM's built-in tools (tasks, docs, search, memories) are available to the AI on every account. External integrations — Google Drive, Docs, Calendar, GitHub — are enabled per account during the internal beta; if mcp servers shows none, your account doesn't have them yet.

Your own servers (mcp add / mcp remove) are experimental and off until you turn them on — Settings → MCP, "Your own MCP servers". Read that panel before you switch it on; three things are worth knowing up front:

BEAM's server makes the connection, not your browser. You give a URL, and BEAM's server opens and holds an outbound connection to it. Only public addresses are accepted — an address on a private network is refused.
A password or token goes in the Authorization header field, never in the URL. BEAM stores it encrypted on its own server and sends it only to the URL you gave — if that server redirects somewhere else, BEAM refuses the redirect rather than forwarding your credential. The panel never shows it back to you. It is at-rest protection and an operator-access bound, not end-to-end encryption: the value is ciphertext in the database and in backups, and BEAM's server holds the key because it is the party making the request. A URL carrying a credential is refused. To change one, remove the server and add it again.
Servers are kept on your account, but BEAM does not reconnect them by itself. After BEAM's server restarts, mcp servers still lists the ones you added — showing as disconnected — and you run mcp connect <id> to open them again. Removing one deletes it from your account; BEAM keeps a record that you added and removed it.

The tools a server you added advertises become tools the AI can offer to call. BEAM asks you before running one, and says what it is about to send — unless you have set that tool to run automatically in Settings → Permissions. Only you can see or call the servers you add.

proposals

Aliases: proposal
Purpose: Review and answer writes an MCP client asked BEAM to make.
Syntax:

>proposals
>proposals approve <n>
>proposals reject <n>

Flags: none
Examples:

>proposals
>proposals approve 1
>proposals reject 2

See also: mcp, action

proposals on its own lists what is waiting, newest first, numbered — plus the last few you have already answered. Nothing in that list has run.

proposals approve <n> runs it, and costs exactly what the command underneath costs anywhere else in BEAM. Most writes show a y/n; the five destructive ones (deleteTask, deleteList, deleteDoc, deleteProject, bulkMutate) show a short code you have to type back, the same as they do from action run. If you have tightened a command with action permissions since the request arrived, the tighter rule is the one you are held to.

proposals reject <n> closes it. Nothing runs, and it stops appearing in the list. There is no confirmation, because declining changes nothing.

You can also answer with n at the approval prompt — that just puts the receipt away. The proposal is still waiting; use proposals reject <n> when you mean it for good.

If you are running the new shell, you do not have to remember to type proposals at all: the Agents Inbox lists the same waiting writes, with what each one will cost you, and its Approve and Reject buttons hand proposals approve <id> / proposals reject <id> to the terminal. The answer still happens there — the buttons arm the receipt, they do not spend it — and a row only leaves the Inbox once the approval or rejection has actually been recorded.

Three things worth knowing. Reads are not proposed: a client searching your tasks gets an answer immediately, because there is nothing to undo. Proposals live on the machine where BEAM is open when the request arrives — they do not appear on your other devices, and switching projects hides the ones that belong to a different one until you switch back. And on an administrator account there are no proposals at all: writes from a connected client run unattended, and the client's receipt says so.