Pages · Orchestra MCP

Commands

`orchestra serve`

Start the MCP stdio server. This is the default command -- running orchestra with no subcommand is equivalent to orchestra serve.

The serve command:

Locates sibling binaries (orchestrator, storage-markdown, tools-features, transport-stdio) next to the orchestra binary.
Generates a temporary plugins.yaml config.
Starts the orchestrator as a subprocess.
Waits for all plugins to register and boot (up to 15 seconds).
Starts transport-stdio with stdin/stdout passthrough.
On exit, kills all child processes and cleans up.

bash

Flag	Default	Description
`--workspace=DIR`	`.` (current directory)	Project workspace directory
`--certs-dir=DIR`	`~/.orchestra/certs`	mTLS certificates directory
`--log=FILE`	`<workspace>/.orchestra-mcp.log`	Log file path

Third-party plugins from the registry (~/.orchestra/plugins/registry.json) are automatically included.

`orchestra init`

Initialize MCP configuration files for your IDE(s). Generates the appropriate JSON/TOML/YAML config so the IDE knows how to start Orchestra as an MCP server.

bash

Flag	Default	Description
`--workspace=DIR`	`.` (current directory)	Project directory to initialize
`--ide=NAME`	(auto-detect)	Target IDE (comma-separated for multiple)
`--all`	false	Generate configs for all 9 supported IDEs

Supported IDEs

Name	Config File	Format
`claude`	`.mcp.json`	JSON (`mcpServers`)
`cursor`	`.cursor/mcp.json`	JSON (`mcpServers`)
`vscode`	`.vscode/mcp.json`	JSON (`mcpServers`)
`cline`	`.vscode/mcp.json`	JSON (`mcpServers`)
`windsurf`	`~/.codeium/windsurf/mcp_config.json`	JSON (`mcpServers`)
`codex`	`.codex/config.toml`	TOML
`gemini`	`.gemini/settings.json`	JSON (`mcpServers`)
`zed`	`.zed/settings.json`	JSON (`context_servers`)
`continue`	`.continue/mcpServers/orchestra.yaml`	YAML

Auto-detection

If --ide is not specified, init checks for existing IDE config directories (.cursor/, .vscode/, .zed/, etc.) and generates configs for detected IDEs. Falls back to claude if none detected.

Examples

bash

Project Name Detection

The init command detects the project name from (in order):

package.json (name field)
go.mod (module path, last segment)
Cargo.toml (name field)
pyproject.toml (name field)
Directory name (fallback)

`orchestra install`

Install a third-party plugin from a GitHub repository.

bash

Flag	Default	Description
`--source`	false	Force build from source (skip binary download)
`--binary`	false	Force binary download (fail if unavailable)

Install Strategy

Binary download (default first attempt): Downloads a pre-built binary from GitHub Releases. Looks for {name}-{os}-{arch}.tar.gz (e.g., my-plugin-darwin-arm64.tar.gz).
Source build (fallback): Clones the repo, runs go build. Requires git and go in PATH.

Manifest Query

After installation, the CLI runs <binary> --manifest to discover the plugin's ID, provided tools, and storage types. This information is stored in the registry.

Examples

bash

Registry

Installed plugins are tracked in ~/.orchestra/plugins/registry.json. Binaries are placed in ~/.orchestra/plugins/bin/.

`orchestra plugins`

List all installed third-party plugins.

bash

Output shows plugin ID, version, repository URL, and capability summary.

`orchestra uninstall`

Remove an installed plugin.

bash

Removes the binary from disk and the entry from the registry. Accepts either the plugin ID or the full repo URL.

Examples

bash

`orchestra update`

Update an installed plugin to the latest version.

bash

Re-runs the install process for the plugin's repo without a version tag, fetching the latest release or source.

`orchestra version`

Print version information.

bash

Output: orchestra <version> (<os>/<arch>, commit <hash>, built <date>)

`orchestra help`

Show usage help with all commands and flags.

bash