Orchestra Server

A Model Context Protocol (MCP) server for the Orchestra API. End users can connect directly to Orchestra's hosted MCP endpoint and authenticate with their Orchestra API key.

Quick Start

Use Orchestra's hosted MCP endpoint:

• URL: https://mcp.getorchestra.io/orchestra
• Required header: Authorization: Bearer <YOUR_ORCHESTRA_API_KEY>
• API key location: Orchestra workspace settings

Available Tools

Tool	Auth required	Purpose	Category
get_pipeline	Yes	Fetch a single pipeline. Provide exactly one selector: pipeline_id, alias, or repository together with yaml_path (GET /pipeline).	Pipelines
list_pipelines	Yes	List pipelines (GET /pipelines).	Pipelines
create_pipeline	Yes	Create a pipeline (POST /pipelines).	Pipelines
update_pipeline	Yes	Update a pipeline by selector (PUT /pipelines).	Pipelines
delete_pipeline	Yes	Disabled by default. Delete a pipeline. Provide exactly one selector: pipeline_id, alias, or repository together with yaml_path (DELETE /pipelines). Set ORCHESTRA_ENABLE_DELETE to expose it.	Pipelines
get_pipeline_data	Yes	Get pipeline data (GET /pipelines/data).	Pipelines
start_pipeline	Yes	Start a pipeline run (POST /pipelines/{pipeline_id_or_alias}/start).	Pipelines
validate_pipeline	No	Validate a full pipeline definition document without creating or updating a pipeline. Use it to check a definition before create_pipeline or update_pipeline (POST /pipelines/schema).	Pipelines
migrate_pipeline	Yes	Migrate an Orchestra-backed pipeline to git-backed storage. Identify it with pipeline_id or alias, and omit working_branch when it equals default_branch (PATCH /pipelines/storage-settings).	Pipelines
import_pipeline	Yes	Import a pipeline (POST /pipelines/import).	Pipelines
get_pipeline_run_status	Yes	Get pipeline run status (GET /pipeline_runs/{pipeline_run_id}/status).	Pipeline Runs
list_pipeline_runs	Yes	List pipeline runs with optional filters. status accepts comma-separated values: CREATED, RUNNING, SUCCEEDED, WARNING, FAILED, CANCELLING, CANCELLED (GET /pipeline_runs).	Pipeline Runs
cancel_pipeline_run	Yes	Cancel a running pipeline run by its ID (POST /pipeline_runs/{pipeline_run_id}/cancel).	Pipeline Runs
get_pipeline_run_lineage_url	No	Build the URL of a pipeline run's lineage graph in the Orchestra UI (derived from ORCHESTRA_ENV).	Pipeline Runs
list_task_runs_for_pipeline_run	Yes	List task runs for a pipeline run (GET /pipeline_runs/{pipeline_run_id}/task_runs).	Task Runs
list_task_runs	Yes	List task runs (GET /task_runs).	Task Runs
list_operations	Yes	List operations (GET /operations).	Operations
list_assets	Yes	List assets (GET /assets).	Assets
get_asset_by_id	Yes	Get an asset (GET /assets/{asset_id}).	Assets
list_task_run_logs	Yes	List task run logs (GET /pipeline_runs/{pipeline_run_id}/task_runs/{task_run_id}/logs).	Logs
download_task_run_log	Yes	Download a task run log (GET /pipeline_runs/{pipeline_run_id}/task_runs/{task_run_id}/logs/download).	Logs
list_task_run_artifacts	Yes	List task run artifacts (GET /pipeline_runs/{pipeline_run_id}/task_runs/{task_run_id}/artifacts).	Artifacts
download_task_run_artifact	Yes	Download a task run artifact (GET /pipeline_runs/{pipeline_run_id}/task_runs/{task_run_id}/artifacts/download).	Artifacts
list_integration_connections	Yes	List integration connections (GET /integrations/connections).	Integrations
list_environments	Yes	List environments (GET /environments).	Environments
create_environment	Yes	Create an environment (POST /environments).	Environments
get_environment	Yes	Get an environment (GET /environments/{environment_id}).	Environments
update_environment	Yes	Update an environment (PATCH /environments/{environment_id}).	Environments
delete_environment	Yes	Disabled by default. Delete an environment (DELETE /environments/{environment_id}). Set ORCHESTRA_ENABLE_DELETE to expose it.	Environments
get_integration_state_for_state_aware	Yes	Get integration state (GET /state/{integration}).	State

Cursor

Add this to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "orchestra": {
      "url": "https://mcp.getorchestra.io/orchestra",
      "headers": {
        "Authorization": "Bearer <YOUR_ORCHESTRA_API_KEY>"
      }
    }
  }
}

Claude Code

Add the hosted server with:

claude mcp add --transport http --header "Authorization: Bearer <YOUR_ORCHESTRA_API_KEY>" orchestra https://mcp.getorchestra.io/orchestra

Other MCP clients

Any MCP client that supports remote HTTP/SSE servers can connect with this shape:

{
  "mcpServers": {
    "orchestra": {
      "url": "https://mcp.getorchestra.io/orchestra",
      "headers": {
        "Authorization": "Bearer <YOUR_ORCHESTRA_API_KEY>"
      }
    }
  }
}

Managing Multiple Workspaces

If you need to connect to multiple Orchestra workspaces, you can set up separate MCP server connections with workspace-specific API keys:

{
  "mcpServers": {
    "orchestra-data-quality-tests": {
      "url": "https://mcp.getorchestra.io/orchestra",
      "headers": {
        "Authorization": "Bearer <DATA_QUALITY_WORKSPACE_API_KEY>"
      }
    },
    "orchestra-sales-integrations": {
      "url": "https://mcp.getorchestra.io/orchestra",
      "headers": {
        "Authorization": "Bearer <SALES_WORKSPACE_API_KEY>"
      }
    }
  }
}

Run Locally

This section discusses how to run the MCP server locally, and is mainly intended for contributors.

Prerequisites

• Python 3.11 or higher
• uv package manager
• Orchestra API key

Install dependencies

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install project dependencies
uv sync

Set API key

export ORCHESTRA_API_KEY="your-orchestra-api-key"

(Optional) Select environment for local runs

For local development, the server defaults to app. You can override it with ORCHESTRA_ENV:

export ORCHESTRA_ENV="dev"

Valid values:

• app (default)
• stage
• dev

(Optional) Enable destructive deletion

By default, the destructive delete_pipeline and delete_environment tools are not registered to avoid accidental destructive actions. To expose them, set ORCHESTRA_ENABLE_DELETE before starting the server:

export ORCHESTRA_ENABLE_DELETE="true"

Only the following values are recognized:

• "true"
• "TRUE"
• "1"

Run the server

python -m orchestramcp.server

The server fetches the Orchestra OpenAPI spec on startup and exposes the operations the API flags for the MCP. Set ORCHESTRA_OPENAPI_URL to point at a specific spec (e.g. a local file) instead of the environment default.

Development

• Run uv run pytest to run tests.
• Run uv run ruff check . and uv run ruff format . to check and format code.

PRs to main will trigger CI checks in GitHub, main branch merges release to the dev & stage environments, and Github releases relase to the production environment.