# Orchestra MCP Server

A Model Context Protocol (MCP) server for the [Orchestra API](https://docs.getorchestra.io/api/introduction). 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](https://app.getorchestra.io/settings/workspace)

## Available Tools

<!-- The table below is generated by scripts/update_readme.py — do not edit by hand. -->
<!-- available-tools:start -->
| Tool | Auth required | Purpose | Category |
|------|---------------|---------|------|
| `whats_broken` | Yes | Failing and warning pipeline runs in a window, pre-joined to the task runs that failed inside them, with messages, platform links and duration anomalies. | Triage |
| `diagnose` | Yes | Deep dive on one task run: parameters, upstream task statuses, log tail and artifact filenames. | Triage |
| `pipeline_context` | Yes | A pipeline's metadata, full definition, integrations, recent run outcomes and median succeeded duration. | Triage |
| `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 |
<!-- available-tools:end -->

### Cursor

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

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

### Claude Code

Add the hosted server with:

```bash
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:

```json
{
  "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:

```json
{
  "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](https://github.com/astral-sh/uv) package manager
- Orchestra API key

### Install dependencies

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

# Install project dependencies
uv sync
```

### Set API key

```bash
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`:

```bash
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:

```bash
export ORCHESTRA_ENABLE_DELETE="true"
```

Only the following values are recognized:

- `"true"`
- `"TRUE"`
- `"1"`

### Run the server

```bash
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.