Tools and MCP

Tools let an agent read information or take actions. Maestrly has three kinds: its own Maestrly tools, the drawer tools you share with the agent (terminal, browser, editor), and the MCP (Model Context Protocol) servers you add. The conversation's mode and permission mode decide what an agent may actually do with them.

Maestrly tools

Since 0.14.0, Maestrly tools are on by default, in groups you can turn on or off separately. Choices you had already made are kept.

Group	What it gives the agent
Terminal	Run and follow commands in the drawer terminals
Browser	Navigate, read, and interact with pages in the drawer browser
Notes	The conversation and project notebooks
Memory	Search and save durable memories
Conversation history	Search earlier parts of the conversation
Debugger	Breakpoints and stepping in the Code tab, which must be open
Artifacts	Publish and update web pages, and read their comments and responses; see Artifacts

Set the defaults in Settings → Maestrly Chat → Tools: the Maestrly tools switch turns them all off or on, and each group has its own switch. In a conversation, open + → Maestrly tools → Choose which groups this conversation gets. Changing one group there pins only that group; the others keep following Settings. Turning off groups you do not need saves context, especially on smaller models. Bots always keep their Maestrly tools on.

The same tab has related settings:

Web search (since 0.18.0) lets models search the web with a web_search tool, in every runtime. Choose Automatic, Tavily (API key), Brave Search (API key), ChatGPT subscription, DuckDuckGo (no key, may be blocked), or Off. Queries go to the provider you pick; Automatic uses a configured API key first, then your ChatGPT subscription, then DuckDuckGo. webfetch still reads a specific URL.
Interactive answers (since 0.18.0) lets models answer with small interfaces you can see and use. See Chat, models, and context. Turning it off saves about 850 tokens of instructions per conversation.

Image generation lets models create images with the generate_image tool (Codex uses its native generator). Since 0.25.0, Generator chooses Automatic (default), ChatGPT, or Google AI (Gemini), consuming that connected subscription's quota. Automatic uses ChatGPT first, then Google AI, while conversations on Google AI draw with their own account first; an explicit choice never falls back to the other subscription (Google AI image generation requires runtime 1.4.0). Compact command output filters verbose output of supported shell commands before it reaches the model, to save tokens.

Drawer tools

The drawer, opened from the conversation header, holds tools you and the agent use together: Browser, Code (an embedded VS Code), Terminal, Plan, Review, and Notes. Use Open a tool (+) and Search tools… to add a tab. Tabs are kept per conversation and you can drag them to reorder.

Settings → Tools & drawer sets the default Drawer tabs order for new conversations and the Tool shortcuts. A tool can also open in a floating window.
Agents are guided to use drawer terminals for processes you want to watch, such as dev servers or watch modes, and their own shell for quick one-off commands. A bash command ends when its shell exits, even if a background program it started still holds its output.
The embedded browser is a real network client, separate from your system browser. It denies site permission requests by default. Sites you sign in to there are also available to agents using the Browser tools (on a bot, the Browser tools drive its own Chromium on its desktop, with its own profile and site logins; see Bots). Since 0.26.0, snapshots include elements inside open shadow roots and same-origin frames, actions scroll a moved element into view or report when it is gone, and a call on an unresponsive page times out so the next navigation or reload restarts it.
Its address bar suggests pages from your history and open tabs, plus Google search suggestions, and completes frequent sites inline. Entries such as localhost:3000 and local IP addresses open over HTTP instead of becoming a search. Cmd+T (Ctrl+T) opens a tab and Cmd+W (Ctrl+W) closes the active one without closing the window. Text you type that is not an address, local host, or IP address goes to Google's suggestion service without cookies.
The history is shared by all conversations and stays on this computer. Remove from history (the × on a suggestion, or Shift+Delete) drops a page, and Clear browsing data deletes the history together with the browser's cache, cookies, and storage.
If the editor freezes, Restart VS Code restarts it without closing the app. Its first setup downloads the VS Code server from Microsoft (showing progress in percent and megabytes, then Installing… and Starting the editor…), and while you have opened the Code tab in the last 14 days, new VS Code versions download in the background.

Permissions

Each conversation has a permission mode in the composer:

Mode	Behavior
Ask for approval	Asks before editing files, running commands, and using the internet.
Approve for me	Asks only for potentially dangerous actions, such as shell commands and folders outside the project.
Full access	Never asks. Use it only for repositories and instructions you trust.

New conversations start with Settings → Execution → Default permission mode (Ask first, Automatic, or Full access). New standalone chats start in the mode you last chose in one (Ask the first time) with Ask for approval. A request offers Allow once, Always allow (saved for the project; Always allow in this chat in a standalone chat), or Deny.

Always allow on a command saves a rule such as npm test *. Since 0.22.0, Maestrly splits a command into every command it would run, the way its shell reads it, and each one must be allowed, so a longer command built to hide a second one no longer matches a saved rule. A command whose structure it cannot read with certainty matches no rule: it asks every time, unless the conversation has full access, and offers no Always allow. Ordinary commands, pipes included, still match their rules.

Modes narrow the tools too: Ask and Plan expose only read-only MCP tools and the Maestrly tools that mode allows. A permission mode is not a sandbox. Commands run with your operating-system account's access, in /bin/sh on macOS and Linux and, since 0.22.0, in Windows PowerShell 5.1 on Windows. Models and subagents are told which shell it is.

Add an MCP server

Open Settings → Maestrly Chat → Tools → MCP servers and choose Add MCP server:

HTTP: the server URL and any headers, one per line, such as Authorization: Bearer ....
stdio: the command (for example npx), its arguments, and environment values, one per line.

Each server has its own on/off switch, and + → MCP servers turns servers on or off for one conversation. Maestrly lists a server's tools only when a conversation first needs them. MCP tools ask for approval when used, under the conversation's permission mode.

Since 0.11.0, MCP connection details (URLs, headers, commands, arguments, and environment values) are encrypted at rest when the operating system's secure storage is available. Without it they stay readable in the app profile, so treat that profile as sensitive. Versions before 0.11.0 cannot read encrypted details: after a downgrade, set those servers up again.

Since 0.20.0, an HTTP server that requires OAuth shows Needs sign-in: choose Sign in and finish in your browser. The host that runs the server keeps the sign-in and renews it. A server can keep several accounts (Add account, Rename, Sign in again, Remove), each applying to all conversations or to selected projects; with several, the model names the account in each call. Servers that do not register apps automatically, such as Google's and Slack's, use your own OAuth client. See Plugins for the details. Since 0.21.0, a stdio server that stops at once says why: its error, with its environment values masked, reaches the model and Test connection.

Bot environments have their own MCP servers, configured from the app; see Bots.

Plugins

Plugins bundle skills and MCP servers, and sometimes commands, agents, and hooks, from Codex, Claude Code, and Agent Plugins sources on Git. Install them in Settings → Maestrly Chat → Plugins, approve what they run, and their parts work the same with every model. Their servers are marked as coming from the plugin and can be switched off per conversation like any other. See Plugins.

Review access before enabling

For every server or tool, ask:

What data can it read?
What can it create, change, send, or delete?
Does it call a remote service?
Which account and permissions does it use?
Will consequential actions wait for your approval?

Enable the smallest set needed. A read-only task rarely needs write or administrative access.

Use tools in a chat

State any important scope in the request, such as a repository, database, workspace, or date range. Watch the first calls and confirm that arguments and targets are correct before allowing broader execution. The selected model must support tool calling, and a server can be unavailable, rate-limited, or limited by its own account plan.

Understand the data path

Local stdio servers run on your machine but may contact external services.
Remote servers receive the request data needed to run their tools.
Your AI provider receives the prompt, tool descriptions, relevant context, and tool results needed for inference.
The embedded browser, web tools, and skill searches contact the sites you or the agent open.
Maestrly has no hosted backend or inference/MCP proxy. Integrations connect directly to their destinations.

Review each provider's and server's privacy terms before sending sensitive data.

Troubleshoot safely

Server does not start: check that the executable exists, the arguments are valid, and required environment values are present.
"Configure it again" message: its stored connection details cannot be read on this computer. Remove the server and add it again.
Authentication fails: check the headers, or choose Sign in again when the server shows Needs sign-in, and use narrow permissions where possible.
Tool is missing: check the server's switch, the conversation's MCP servers and Maestrly tools choices, and the mode; Ask and Plan expose only read-only MCP tools.
Call times out: check network access, server health, and rate limits before retrying.
Unexpected action: stop the run, turn the server or tool off, review what it did, and rotate exposed credentials if needed.

Next: Plugins.