Settings

Settings: MCP

Decide which agents and outside tools may connect to the Orkestra MCP server, and which tools each of them may use.

On this page

Purpose

Use MCP settings to choose which Orkestra tools Helm, launched agents, and external clients can use. You can attach Orkestra tools automatically to new terminals or connect another tool over your network.

You set rules for three kinds of caller:

  • Helm, the built-in assistant. See Helm.
  • Agents in terminals that Orkestra launches with the Orkestra MCP tools attached.
  • Outside tools that connect over a network port. This works only when you turn on the external server.

The MCP pane decides which of these callers can connect and which tools each one may use.

Where to find it

Click the Settings button in the top bar. In the Settings window, click MCP in the list on the left. The pane opens.

Every switch and field in this pane changes a draft. Orkestra uses the new values after you click Apply or OK. Cancel drops the draft. For the window buttons, search and Reset, see Settings: the window, appearance, terminal, workbench and notifications.

What you see

The pane has eight groups. The first two are open; click a group's title to open or close the remaining six.

Auto-attach Orkestra MCP

  • Attach to launched agents — off by default. When on, new Claude, Codex, and OpenCode terminals get Orkestra tools automatically. Cursor and Antigravity use their own MCP configuration, so this switch does not affect them. When off, each launch keeps its existing per-launch choice.

External MCP server

  • Enable external server — off by default. When it is off, the server is available only on this computer. Turn it on to allow connections over your network; clients must provide the token.
  • Port — the network port for external connections. The default is 41025; allowed values are 1024–65535.
  • Auth token — external clients must send this token with each request. Orkestra stores it in Settings so you can copy it again. The row has two forms:
    • With a token: a read-only text field that shows the token, a Copy button and a Regenerate button. The token is always visible. The pane has no show or hide button.
    • Without a token: the text "No token set" and a Generate token button.
  • A status line under the token. See "States and messages".
  • The client configuration block appears only while Enable external server is on. Its five buttons copy ready-to-paste configurations containing the server address and token: Copy Claude Code config, Copy Codex config, Copy Cursor config, Copy OpenCode config and Copy Antigravity config. Generate a token first if none exists.

Tool lists. Each row is a checkbox for one tool. Checked means that caller can use it. Unchanged rows keep their defaults; tools that are off by default are marked · sensitive.

Helm tools

  • Helm can use all tools by default except Get settings, Update settings and Remote helm message, which are off and marked · sensitive.
  • Reset to defaults restores the defaults for Helm tools, Memory (Helm) and Usage limits.

Internal tools

  • This list controls Orkestra tools available to agents running in terminals. All are on by default.
  • Reset to defaults restores the defaults for Internal tools and Memory (internal).

Memory (internal)

  • Controls whether agents in terminals can use Memory save, Memory search, Memory list and Memory forget. All are on by default. This group has no reset button; use Reset to defaults in Internal tools. Turning off Helm memory in Settings: Helm disables these tools regardless of these checkboxes.

Memory (Helm)

  • Controls whether Helm can use Memory save, Memory search, Memory list and Memory forget. All are on by default. This group has no reset button; use Reset to defaults in Helm tools. Turning off Helm memory in Settings: Helm disables these tools regardless of these checkboxes.

Usage limits

  • The Get usage limits tool lets Helm read the same read-only usage data shown in the Usage limits panel. It is on by default. This group has no reset button; use Reset to defaults in Helm tools.

External tools

  • Controls what connected clients can do. Sensitive or destructive tools are off by default and marked · sensitive: Create project directory, Import project, Clone project, Scan project folder, Import project scan, Run in terminal, Send terminal keys, Close terminal, Delete task, Delete group, Delete project, Delete routine, Remove worktree, Rename project, Rename group, Trash task, Bulk trash tasks, Merge tasks, List files, Read file and Remote helm message. Other tools are on by default.
  • Reset to defaults restores only the External tools defaults.

How to

Attach the Orkestra tools to every launched agent

  1. Click the Settings button in the top bar.
  2. Click MCP in the Settings list.
  3. Find the Auto-attach Orkestra MCP group.
  4. Turn on Attach to launched agents.
  5. Click OK.

Result: Each Claude, Codex or OpenCode terminal that you launch next gets the Orkestra MCP tools. Terminals that already run keep what they have.

Turn on the external MCP server

  1. Click the Settings button in the top bar.
  2. Click MCP in the Settings list.
  3. Find the External MCP server group.
  4. Turn on Enable external server.
  5. Optional: type a number from 1024 to 65535 in the Port field.
  6. If the Auth token row shows "No token set", click Generate token.
  7. Click Apply.
  8. Read the status line under the Auth token row.

Result: The status line reads "Listening on port 41025 (all interfaces). Changes apply on Apply/OK." The number is your port.

Copy the access token

Before you start, check the Auth token row. If it shows "No token set", click Generate token first.

  1. Click the Settings button in the top bar.
  2. Click MCP in the Settings list.
  3. Find the Auth token row in the External MCP server group.
  4. Click Copy.

Result: The button text changes to Copied. The token is on your clipboard.

Replace the access token

  1. Click the Settings button in the top bar.
  2. Click MCP in the Settings list.
  3. Find the Auth token row in the External MCP server group.
  4. Click Regenerate.
  5. Click Apply.

Result: The field shows a new token. An outside tool that sends the old token is refused. Copy the new token or a new client configuration for each outside tool.

Copy a client configuration for an outside tool

Before you start, turn on Enable external server and make sure a token exists. See "Turn on the external MCP server".

  1. Click the Settings button in the top bar.
  2. Click MCP in the Settings list.
  3. Find the client configuration buttons in the External MCP server group.
  4. Click the button for your tool, for example Copy Claude Code config.

Result: The button text changes to Copied. The clipboard holds a ready-to-paste configuration with the address and the token. Paste it into the MCP configuration of that tool.

Switch a tool off for one kind of caller

Before you start, choose the group: Helm tools for Helm, Internal tools for agents in terminals, or External tools for outside tools.

  1. Click the Settings button in the top bar.
  2. Click MCP in the Settings list.
  3. Click the title of the group, for example Internal tools, to open it.
  4. Click the row of the tool, for example Run in terminal.
  5. Click OK.

Result: The check box of the row is empty. The tool is off for that caller. Click the row again and apply to turn the tool on.

Restore the default tools of a group

  1. Click the Settings button in the top bar.
  2. Click MCP in the Settings list.
  3. Click the title of the group, for example External tools, to open it.
  4. Click Reset to defaults.
  5. Click OK.

Result: The rows of the group show their defaults again. Your own choices in that group are gone. Read "What you see" for the groups that also clear a memory or usage group.

States and messages

Status line under the Auth token row. It shows the server that runs now. It does not show edits that you have not applied.

  • "External server is off. Enable it, generate a token, then Apply to start it." — the server is off, or the status is not known yet.
  • "Starting…" — the server is on and does not listen yet.
  • "Listening on port <port> (all interfaces). Changes apply on Apply/OK." — the server runs. Outside tools can reach it with the token.
  • "Not listening — <reason>" — the server could not start. For example: "Not listening — Port 41025 is already in use." Type another number in Port and click Apply. Other reasons show the system error text.

Token and copy buttons

  • "No token set" — no token exists. The Copy … config buttons are disabled.
  • Copied — the last copy worked. This text replaces Copy or Copy … config.

Tool rows

  • "· sensitive" — the tool is off by default for that caller. You can still turn it on.

What an agent sees when a call is refused. The agent can show these texts in its terminal.

  • Tool "<name>" is disabled by Orkestra MCP settings. — the tool is off for that caller.

Limits and tips

  • Draft until Apply or OK. The status line and the running server follow the applied values. The copy buttons use the values in the pane now. Click Apply before you copy a configuration, so the server and the copy match.
  • An off tool is hidden and refused. An agent reads its tool list when it connects. A tool that is off is not in the list. A call to a tool that you turned off later is refused. After you turn a tool on, an agent that is already connected can see it only when it connects again.
  • Auto-attach. This uses the built-in server on your computer; it does not need the external server and takes effect at the next launch. Cursor and Antigravity use their own MCP configuration: turn on the external server, copy a client configuration here, and add it to that app. The switch also controls whether new terminals receive Orkestra's built-in guides.
  • External server. It opens a network port on all interfaces. A client must send the token. A server without a token accepts no client. Orkestra stores the token in its settings as plain text. A copied configuration contains the real token. Keep it private.
  • Address in the copied configuration. It uses "localhost" and your port. For a client on another computer, replace "localhost" with the address of this computer.
  • Memory and usage tools. Outside clients never get the memory tools or "Get usage limits". No switch exists for this. Agents in terminals always keep "Get usage limits". The master switch for memory is in the Helm settings. See Settings: Helm and Helm memory.
  • Update settings. In Internal tools the row "Update settings" is on by default. Turn it off there if agents in terminals must not change application settings.
  • Tour and guide rows. "Show ui tour" lets an agent point at a control on your screen with the tour callout (see First-run setup, Getting started and tours). "Read user guide" lets an agent read this guide. Both rows are on by default for Helm, agents in terminals and outside tools. Turn a row off to stop that kind of caller. A phone (Telegram) session can read the guide but never shows a tour.
  • Approvals are separate. These switches say which tools exist for a caller. They do not ask you before a risky action. See Approvals.