Skip to content

Configure MCP servers

Use Settings → All projects → MCP Servers to connect Model Context Protocol (MCP) servers. Connections and selected tools apply across projects on this Mac. You can run a local process or connect to a remote Streamable HTTP endpoint.

Have the executable and arguments, or the server’s endpoint URL, ready. Connect starts a local command as your macOS user or contacts the remote server. Review it before connecting.

  1. In MCP Servers, select Add server.
  2. Under Location, choose Remote or Local.
  3. For Remote, enter Server URL. For Local, enter Executable and Arguments, one argument per line. Name (optional) lets you replace the suggested name.
  4. Add any required headers or environment variables, as described below.
  5. Select Connect. If the server needs OAuth, select Sign in and finish in your browser.
  6. In Tools for new Sessions, select the tools you want to offer.
  7. Select Add server to save the connection and tool selection.

Connecting alone does not save the server. Newly discovered tools start unselected.

Remote servers support custom Headers. Local processes support Environment variables. Each value has two choices:

  • Stored secret is a write-only value. After saving, the field shows Stored and accepts a replacement without revealing the old value.
  • Environment variable stores a reference such as ${API_KEY}. Volli resolves it from the app’s environment when the server connects.

For an API-key server, use the header name and value format its documentation requires. Keep credentials out of Server URL. Volli sends credentials only over HTTPS or to this machine, and does not forward them across origins.

Remote servers without an Authorization header can use OAuth. Sign in opens the browser only when you request it. Connections can reuse and refresh a saved token; a server that needs another sign-in shows that action. Cancel sign-in stops waiting, and Sign out removes the saved sign-in.

For a server that requires a pre-registered OAuth client, expand Custom OAuth client. It provides Client ID, Client secret, Callback port, Callback URL, and Scope. Use the values registered with that server. Adding your own Authorization header bypasses OAuth sign-in.

Open a saved server by its name or use its menu’s Choose tools action. Filter tools narrows the list. Select all and group checkboxes affect the listed tools. A read-only grouping reflects the server’s own claims, not a Volli security guarantee. Select Save to keep your choices.

Use Edit connection to change the command, endpoint, or credentials. Refresh tools reads the catalog again. Existing tools on the same endpoint keep their choices; a changed endpoint starts with its tools unselected. Recent activity records configuration operations and their outcomes.

The server’s enabled switch and tool selection determine what new root Sessions receive. Switching a server off keeps its configuration for existing Sessions and their recorded tool names, but calls to that server fail until you enable it again.

Existing Sessions keep their recorded tools and can gain additions. Tools routed only through Code Mode can become callable before the next program. Other additions wait for a cold prompt cache, compaction, or model switch. Updates appear in an expandable Tools updated transcript row.

Delegated helpers inherit their parent’s recorded MCP tools, including refreshed additions. They do not independently receive the later global selection. Running helpers gain additions within their parent’s tool surface.

Large servers use Code Mode discovery rather than declaring every tool on every request. This applies above 20 enabled tools or about 3,000 tokens of definitions, including in Direct tools mode. Enable only what you need.

Use the server menu’s Remove action. Existing Sessions keep its tool names, but calls return an unavailable error while the configuration is missing. Keep a server enabled while existing Sessions still need it. Disabling keeps the configuration for later use, but blocks calls until you re-enable it.

A local MCP command runs as you. A remote server receives the arguments sent to its tools. Treat metadata, descriptions, and results as untrusted content, and review tools before enabling them.

Volli supports standard input/output and Streamable HTTP, not legacy SSE-only endpoints. See Local data and network access for credential storage and other network connections.