AI agents and MCP

Orca is an MCP server. Connect Claude or another AI tool and it can do what you'd do in Orca: start a project from a folder, switch its profiles, read logs, add an HTTPS route, run a worktree instance of a branch and tell you its URL. You don't need an API key, and you don't copy any tokens.

#Connect in one click

Open Settings → AI & agents. Under Connect your AI tools, Orca lists the AI tools it supports and shows which of them are on this computer:

Click Connect next to a tool. Orca adds one entry named orca to that tool's config and leaves the rest of the file alone. Then:

• Claude Code and Codex: start a new session. In Claude Code, /mcp lists Orca.
• Claude Desktop: quit and reopen it.
• Cursor, VS Code and Windsurf: Orca shows up in the tool's MCP settings.

Disconnect removes that entry again. While none of your AI tools has Orca, the dashboard shows a one-line invitation to connect the ones it found.

Then ask, for example:

• "Start the project in ~/code/shop and give me its URL."
• "Why does the api container keep restarting?"
• "Turn on the search profile for shop."
• "Run my feature branch as its own instance, with its own database."

#Why there's no token

The entry Orca adds runs orca mcp, the Orca CLI as a local MCP server over stdio:

{
  "mcpServers": {
    "orca": { "command": "/Users/you/Library/Application Support/orca/bin/orca", "args": ["mcp"] }
  }
}

orca mcp reads the daemon's API token from Orca's own config file each time it starts, and passes your AI tool's requests on to the daemon. The token never appears in the AI tool's config, so there's nothing secret to commit or paste into a chat, and if you reset Orca's token, connected tools keep working.

Orca keeps its own copy of the CLI in its data folder (~/Library/Application Support/orca/bin on macOS, ~/.local/share/orca/bin on Linux, %LOCALAPPDATA%\orca\bin on Windows) and refreshes it whenever the app starts. Updating Orca or moving the app doesn't break your AI tools' configs.

If Orca isn't running when your AI tool calls it, the tool gets a clear error saying so instead of hanging.

#Connect from the terminal

The same works from the CLI, for example on a server or in a dotfiles script:

orca mcp install            # connect every supported AI tool found on this machine
orca mcp install cursor     # or just one: claude-code, claude-desktop, cursor, vscode, windsurf, codex
orca mcp status             # which tools are found and connected
orca mcp uninstall          # remove Orca from every tool it was added to

#Other MCP clients

Any MCP client that starts stdio servers can run Orca. Give it the command orca with the argument mcp, the same as the JSON above. Settings → AI & agents → Another MCP client? shows the block with the full path on your machine, ready to copy.

#Manage a remote host

If you've added a remote Orca host in Remote hosts, an AI tool can manage that host instead of this computer. Add --host with the host's name to the arguments:

{ "command": "orca", "args": ["mcp", "--host", "build-server"] }

orca mcp --host uses the URL, token and TLS setting Orca Desktop already stores for that host. Connect it under a second name, such as orca-build-server, to have both.

#HTTP endpoint (advanced)

The daemon also speaks MCP over HTTP at http://127.0.0.1:9477/api/v1/agent/mcp, for clients that can't start local commands. This one needs the API token as a Bearer header. Settings → AI & agents → HTTP endpoint (advanced) shows and copies the token. Orca stores it as api_token in its config file:

claude mcp add --transport http orca http://127.0.0.1:9477/api/v1/agent/mcp \
  --header "Authorization: Bearer YOUR_TOKEN_HERE"

The endpoint takes JSON-RPC over POST and supports initialize, ping, tools/list and tools/call (protocol versions 2025-06-18, 2025-03-26 and 2024-11-05).

#What the agent is told

When an AI tool connects, Orca sends a short map of its concepts (stacks, orca.yaml, workspaces, the gateway, databases, worktrees) and instructions on when to use which tools: deploy_project for a folder that isn't running yet, the instance_* tools inside a git worktree, a snapshot before risky database changes, and to ask before removing anything or importing over a database.

For anything deeper, the AI tool reads Orca's own documentation through orca_docs: these pages, as they were when your Orca was built, so the keys it writes into orca.yaml or orca-workspace.yaml match the version you run. It's told to read the relevant page before writing either file, rather than guessing. Each tool also carries hints that clients use to decide when to ask you first:

• Tools that only read (listings, logs, status, read_orca_yaml) are marked readOnlyHint, so clients may run them without asking.
• Tools that only add or start something (starting or restarting a container or stack, pulling images, adding a route or project, starting a build or an instance) are marked as not destructive.
• Everything else that changes state is marked destructiveHint, from stopping a container or switching profiles to running a command in a container, applying Kubernetes YAML or removing anything, so clients that respect the hint ask you first.

#Agents working in git worktrees

If your project is registered with Orca, each git worktree can run its own instance of the app: its own URLs and ports, with databases and other shared services running once. An agent working in a worktree passes its worktree path to the instance_* tools:

1. instance_up starts or rebuilds this branch's instance and returns its URLs, host ports and the path of its .orca/env file.
2. instance_status or instance_env gives the URLs and ports to test against.
3. instance_logs shows what went wrong.
4. instance_down stops it when the work is done.

Before running migrations or writing test data, ask for an own copy of the database so other worktrees aren't affected, for example "data": {"postgres": "own-database"} on instance_up. The modes are shared, own-database and own-server.

When you set up a project for worktrees in Orca, the setup dialog can also add a short section to the project's CLAUDE.md or AGENTS.md that tells coding agents to use orca up, .orca/env and these MCP tools. The same commands are available from the shell: see CLI reference.

#OpenAI-compatible endpoint

Agent frameworks that use OpenAI-style function calling can send tool calls to:

POST http://127.0.0.1:9477/api/v1/agent/openai/chat/completions
Authorization: Bearer YOUR_TOKEN_HERE

This endpoint doesn't run a model. It executes the tool calls you send and returns their results:

• It reads tool_calls from the last assistant message in messages, or from a top-level tool_calls array.
• Each result comes back in tool_results as a role: "tool" message with the matching tool_call_id.
• A request without tool calls returns the tool list in OpenAI function format.
• At most 16 tool calls are accepted per request.

curl -X POST http://127.0.0.1:9477/api/v1/agent/openai/chat/completions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "role": "assistant",
      "tool_calls": [{
        "id": "call_1",
        "type": "function",
        "function": { "name": "container_logs", "arguments": "{\"id\": \"web\", \"tail\": 50}" }
      }]
    }]
  }'

#Direct tool execution

For scripts and custom integrations, list the tools and call one at a time.

# Tool definitions in OpenAI function format
curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:9477/api/v1/agent/tools

# Run one tool
curl -X POST http://127.0.0.1:9477/api/v1/agent/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tool": "diagnose_container", "arguments": {"id": "web"}}'

A successful call returns {"result": ...}. A failed one returns HTTP 400 with {"error": "..."}.

#Tool reference

Orca has 74 agent tools. The same set is available over MCP, the OpenAI-compatible endpoint, direct execution, and to the built-in AI assistant.

#Containers

#Diagnostics

#Images

#Stacks

#Gateway

#Storage and networking

#Templates

#Builds

#Kubernetes

#Orca itself

Ask "is my Orca up to date?" or "update Orca". When you ask about a feature your version doesn't have yet, the AI tool can check whether a newer release has it.

#Workspace

#Databases

See Databases, including asking an AI tool to move every project onto shared servers.

#Worktree projects and instances

The instance tools each take worktree, the absolute path of the git worktree.

#Related

• AI assistant: the chat window built into Orca, which uses these tools.
• REST API: every daemon endpoint.
• CLI reference: orca up, orca env and the rest from the shell.