Orca v0.5.6

Orca v0.5.6

Changes since v0.5.5:

• orca mcp add, list, get, remove, login and logout manage MCP
  servers from the command line, local or remote, without editing the config by
  hand.
• MCP servers connect in the background, all at once, as soon as the TUI opens.
  /mcp and MCP prompt commands work before your first message, and a turn
  waits only for the servers still connecting.
• Remote MCP servers use streamable HTTP as the MCP spec defines it, fall back
  to legacy HTTP+SSE servers, and can sign in with OAuth or a bearer token taken
  from an environment variable.
• Tools a server marks read-only no longer ask for approval in suggest mode
  and are allowed in plan mode.
• Permission rules can name MCP tools and whole MCP servers, and the approval
  panel can save "always allow this tool" or "always allow this server" to your
  config.
• /mcp in the TUI shows each server's status, tools, and prompts, and
  reconnects, logs in, or logs out. A login that waits for the browser can be
  cancelled.
• MCP prompts run as slash commands: /mcp__<server>__<prompt> args. Esc
  cancels one the server has not answered yet.
• enabled_tools and disabled_tools choose which of a server's tools Orca
  registers.
• deepseek-flash (and auto) now sees the images that MCP tools return.
• In a folder you have not reviewed yet, the workspace review always comes
  first: orca "<prompt>" sends the prompt, and --continue or --resume
  opens the conversation, only once you accept.
• A config.toml that cannot be read or parsed is left out with a warning
  instead of in silence, and config errors never quote the file's values.

Changes

Add a server with one command

orca mcp add docs -- npx -y @acme/docs-mcp        # local (stdio)
orca mcp add tracker --url https://mcp.example.com/mcp
orca mcp list
orca mcp login tracker

• add writes a [[mcp_servers]] entry to ~/.orca/config.toml. Your other
  entries and comments are kept, and a config that does not parse is never
  overwritten. A file that lists its servers as an inline array,
  mcp_servers = [{ … }], gets the new entry in that array; list, get, and
  remove read both forms.
• For a local server, pass -e KEY=VALUE to set its environment. For a remote
  one, use --transport http|sse, --header "Name: value",
  --bearer-token-env-var NAME, --client-id ID, and --callback-port PORT.
• list and get (both accept --json) show the auth state but never print
  environment values, header values, or tokens. An entry that does not load is
  named on stderr with the reason, the other servers are still listed, and
  list exits 1.
• remove also deletes the server's saved login.
• Server names may use letters, digits, -, and _. A name that normalizes
  to the same tool prefix as an existing server (GitHub and github) is
  refused.
• Every edit of config.toml (orca mcp add and remove, a saved
  always-allow rule, a saved model choice) holds a lock on
  config.toml.lock, so two edits at once, even from two processes, no longer
  lose one of them.
• A change takes effect in new sessions. A server added while the TUI is open
  appears after you restart it; a new login is picked up by reconnecting the
  server from /mcp.

Connecting at launch

• The TUI starts a new conversation's MCP servers as soon as it opens, all at
  once, in the background. On the first run in a folder they start once you
  have reviewed the workspace, and entered an API key when none is set.
• An enabled server shows starting until it connects, fails, or turns out to
  need a login. A disabled server is listed as disabled and never connected.
• Before your first message, /mcp already shows each server's real status,
  tools, and prompts; r, l, and o work; and each connected server's
  prompts are slash commands. The conversation your first message starts takes
  over the servers as they stand, without connecting them again.
• Before its first model request, a turn waits only for the servers still
  connecting, so the model is offered every tool they bring. The status line
  says connecting MCP servers meanwhile, and Esc interrupts the turn, wait
  included. Each request of a connection (initialize, tools/list,
  prompts/list) is bounded by the server's startup_timeout_ms, 30 seconds
  unless set.
• orca exec, ACP, and daemon sessions connect their servers in parallel too.
• Quitting stops every stdio server, those still connecting too, and so does
  Ctrl+C while orca exec waits for them.

Remote servers

• transport = "http", the default for --url, is streamable HTTP:
  • Orca sends the Accept and MCP-Protocol-Version headers and keeps the
    Mcp-Session-Id.
  • When a session expires, Orca initializes it again once and retries the
    request.
  • Closing ends the session.
• transport = "sse" now tries streamable HTTP first. It falls back to the
  2024-11-05 HTTP+SSE transport only when the server answers the first request
  with 400, 404, or 405.
• Orca declares protocol version 2025-06-18 and accepts 2025-06-18, 2025-03-26,
  and 2024-11-05.
• tools/list, prompts/list, resources/list, and
  resources/templates/list follow nextCursor, up to 100 pages, and stop at
  a cursor they have already seen.
• Orca answers a server's ping on every transport, and answers any other
  server request it does not handle with JSON-RPC error -32601 instead of
  leaving it unanswered.
• A response sent as an SSE stream is read only until the matching response
  arrives, so a server that keeps the stream open no longer holds up the
  request.

Signing in

• bearer_token_env_var = "NAME" sends Authorization: Bearer <value of NAME>.
  The token never goes into the config.
• A server that answers 401, and has neither a static Authorization header
  nor a bearer variable, uses OAuth 2.1 with PKCE.
  • orca mcp login <name>, or l in /mcp, opens the browser and also
    prints the URL.
  • While a login in /mcp waits for the browser, l again cancels it and
    frees the callback port. Once the browser is back, the login finishes.
  • Tokens are saved owner-only in ~/.orca/mcp-credentials.json and
    refreshed automatically.
  • When a refresh fails, the error points to orca mcp login <name> and
    /mcp.
  • orca mcp logout <name>, or o in /mcp, deletes the saved tokens.
• OAuth discovery does not follow a redirect from https to plain http.

Approvals

• Read-only tools. A tool whose annotations say readOnlyHint: true, and
  not destructiveHint: true, counts as a read. Orca trusts the server's
  claim, as Claude Code and Codex do.
• Rules.
  • tool = "mcp__github__*" or tool = "mcp__github" covers a whole server.
  • tool = "mcp__github__create_issue" covers one tool.
  • MCP rule names are normalized the way Orca names MCP tools: lowercase,
    with other characters turned into _. Use the name /mcp shows.
  • pattern is now optional for every rule, and leaving it out covers every
    call to the tool. For bash that means every command.
• Approval panel. MCP tools get two more choices: 5 always allows the
  tool and 6 always allows its whole server. Both are saved to your config
  as a rule, in [[permissions.rules]] or in an inline rules = [...] array
  when the file uses one.
• When a stricter rule in your config (deny or prompt) still covers the
  tool, saving says saved, but a stricter rule in your config still applies to <tool>. The call still runs, and the rest of the session still skips the
  prompt.

/mcp

• Each server shows one of:
  • starting
  • connected · N tools
  • failed: <reason>
  • needs login
  • disabled
• The details list the server's tools, one to a line with read-only in front
  where the server says so and the name a rule should use; its prompts with
  their arguments (review_pr <pr> [branch]); prompts unavailable: <reason>
  when prompts/list failed; and its tool filters.
• r reconnects, l logs in, and o logs out. A server's line shows what is
  running on it: reconnecting…, waiting for browser login… (l to cancel),
  finishing login…, or logging out….
• A status changes as soon as the server's state does, while a turn runs too.
• In an orca attach session, /mcp explains how to make a new login take
  effect.

Prompts as slash commands

• /mcp__github__review_pr 123 main fills the prompt's arguments in order,
  and the last argument takes the rest of the line.
• A missing required argument shows the usage instead of sending anything.
• The expanded prompt is sent as plain text, so @ in a server's prompt is
  never expanded into a file. It goes only to the conversation where you ran
  the command.
• Esc cancels a prompt the server has not answered yet, and says
  MCP prompt /mcp__<server>__<prompt> cancelled. What the server returns
  later is dropped.
• A prompt command run before your first message starts the conversation.
  While its server is still connecting, Orca says
  MCP server <name> is still connecting; try again in a moment.

Tool filters

• enabled_tools is an allow-list and disabled_tools a deny-list, both of
  the server's own tool names.
• The allow-list applies first, then the deny-list. An empty enabled_tools
  enables nothing.

Images from MCP tools

• deepseek-flash and auto see the images an MCP tool returns.
  • PNG, JPEG, GIF, and WebP are accepted, up to 5 MiB each, in responses of
    up to 16 MiB.
  • Each request carries at most the 3 newest tool images.
  • Resuming a session does not reload earlier tool images.
• Other models get a note in place of the image.

Server state

• A failure on a connection the server has since replaced no longer marks the
  server, and an older reconnect never overwrites a newer one.
• needs login also comes from a prompt or resource request, and clears as
  soon as a request to the server succeeds.
• Reconnecting a stdio server stops the old process before starting the new
  one, so a server that listens on a fixed port can restart. A stdio server
  that cannot start again is marked failed, with the reason.
• After Esc interrupts a call to a stdio server, the server is started again
  with its full startup timeout before its next request, so a server slow to
  start, such as one run through npx or uvx, stays usable. Esc stops that
  start too, as it does the start that follows a call the server failed (a
  crash or a timeout), and a call cancelled before it reaches the server is
  never sent.

Starting the TUI

• orca "<prompt>" in a folder you have not reviewed shows the workspace
  review first. The prompt is sent once you accept (and enter an API key, when
  none is set); E exits without sending it. Before, the prompt ran at once
  and the review never showed.
• orca --continue and orca --resume <id> open their conversation only once
  you accept, with a prompt given with them sent after its history. Before,
  the resumed conversation replaced the review screen and started its MCP
  servers.
• When the conversation --continue or --resume names cannot be opened, the
  prompt given with it, and whatever you send next, start a new conversation.
  Before, each was rejected until /new.
• MCP servers start only after the review, too.

Configuration

• A config.toml that is not valid TOML, is not UTF-8 text, or cannot be read
  is left out with a warning, such as
  orca: warning: config parse error in <path>, ignoring it: TOML syntax error at line 2, column 22: invalid basic string. Before, it was left out in
  silence, and Orca ran without your settings.
• Config errors name the line and column, or the key and the type it needs,
  and never the value found, so a token in the file stays out of logs and bug
  reports. The same goes for a file in $ORCA_HOME/tools that does not load.

Compatibility

• Servers that mark tools readOnlyHint now run those tools without asking
  in suggest mode, and are allowed in plan mode.
• MCP servers in your config now start when the TUI opens, not at your first
  message.
• transport = "sse" servers now get streamable HTTP first. A server that
  accepts it is used that way.
• Stdio servers are now checked like remote ones. A server that answers
  initialize with a protocol version other than the three above fails to
  connect.
• This release does not keep MCP data readable by older versions. Orca v0.5.5
  and earlier cannot read:
  • a session this version wrote while an MCP server was configured;
  • a session that holds a rule without pattern, which includes every saved
    "always allow";
  • a config that uses transport = "http" or a rule without pattern.
• In the app-server protocol, an addRules permission update without
  ruleContent now covers the whole tool instead of the glob *.

Configurations and sessions from earlier versions remain readable.

Verification

cargo fmt --all -- --check
node --test scripts/test-validate-runtime-surface-contract.mjs
node scripts/validate-runtime-surface-contract.mjs
node --test scripts/test-validate-windows-platform-boundaries.mjs
node scripts/validate-windows-platform-boundaries.mjs
node scripts/release/verify-version-sync.mjs
node scripts/release/test-verify-version-sync.mjs
node scripts/release/test-stage-npm.mjs
node scripts/release/test-verify-published.mjs
node scripts/test-repository-hygiene.mjs
cargo nextest run --workspace --all-targets --locked --profile ci --no-fail-fast --retries 0
cargo nextest run -p orca-tui --lib --locked --profile ci-serial --retries 0
cargo nextest run --test tui_pty_contract --locked --profile ci-serial --retries 0
npm --prefix site run build
npm --prefix site run check:seo

Upgrade

npm install -g @blade-ai/orca@0.5.6
orca --version