Beam AI
AI tools and MCP
What the assistant can do on your Mac, and who approves it.
When a model supports tools, Beam gives it 19 built-in tools. Read-only tools run without asking. Tools that change something ask first, unless you turned on Run tools automatically in Settings → AI (the setting is the inverse of the code's aiToolsConfirm preference).
Read-only
| Tool | Does | Shares with the model |
|---|---|---|
| current_context | Describes your situation. | Frontmost app, time, clipboard text, timers, calendar events. |
| search_files | Searches files. | Matching file names. |
| search_notes | Searches your notes. | Matching note text. |
| search_manual | Searches Beam's manual. | |
| web_search | Web search through DuckDuckGo Lite. | Your query goes to DuckDuckGo. 8 results return. |
| screenshot | Looks at your frontmost window. | A JPEG scaled to 1400 px (Screen Recording). |
| calendar_events | Reads your calendar. | Event details. |
Actions (ask first)
| Tool | Does |
|---|---|
| open | Opens an app, file or URL. |
| create_note | Makes a note. |
| start_timer | Starts a timer. |
| arrange_window / arrange_windows | Snaps windows. |
| create_snippet | Adds a snippet. |
| create_command | Adds a command. |
| create_script | Writes a script in ~/.config/beam/scripts. |
| copy_to_clipboard | Copies text. |
| run_command | Runs one of your Beam commands. |
| open_settings | Opens a settings pane. |
| set_theme | Switches theme. |
A single reply can chain up to 30 rounds of tool calls. Press Esc to deny a pending approval.
MCP servers
Add Model Context Protocol servers in Settings → AI → MCP Servers. Beam starts each as a local process (via sh -c with the command you enter) and speaks JSON-RPC over standard input and output. The server's tools join your chats as mcp_* tools. When approvals are on, every MCP tool call asks first, every time.
Choosing a model matters
With a local model, tool results stay on your Mac. With a cloud model, anything a tool returns is sent to that provider as part of the conversation.