Orchestra MCP Server

Official

by orchestra-hq

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Start a pipeline run

start_pipeline

Start a pipeline run. The pipeline can be identified by alias or pipeline ID.

Instructions

Start a pipeline run. The pipeline can be identified by alias or pipeline ID.

All request body fields are optional. Use branch and commit for Git-backed pipelines, versionNumber for Orchestra-backed published versions, and runInputs for values required by pipeline inputs. The response includes a pipelineRunId you can use to poll run status.

Any other JSON body, such as a webhook sent by another tool, still starts the run, with default options; requestBodyMessage and requestBodyErrors in the response say which happened. Either way the whole body is available to the pipeline's webhook.runInputs as ${{ outputs.payload }}, for example ${{ outputs.payload.connection_id }}, or ${{ outputs.payload['connectionId'] }} for a key with capitals, so task conditions can act on it through ${{ inputs.<name> }}. Bodies over 64 KiB are not kept.

Input Schema

Name	Required	Description
`data`	No
`branch`	No
`commit`	No
`ciRunId`	No
`taskIds`	No
`runInputs`	No
`environment`	No
`versionNumber`	No
`retryFromFailed`	No
`environmentOverrides`	No
`pipeline_id_or_alias`	Yes	Pipeline ID or alias.
`continueDownstreamRun`	No
`X-Orchestra-Account-Id`	No	Act on this account rather than the one the credential resolves to. Omit it to use the credential's own account. An API key is issued to a single account, so it may only name that account; an OAuth token may name any account its grant covers.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed12 schema fields changedv2026.10.12-0Oct 14, 2026

removedInput schema / properties / body

Removed value: -{
-  "anyOf": [
-    {
-      "additionalProperties": false,
-      "description": "Full webhook request body for triggering a pipeline run.",
-      "properties": {
-        "branch": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "ciRunId": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "commit": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "continueDownstreamRun": {
-          "anyOf": [
-            {
-              "type": "boolean"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "data": {
-          "default": [],
-          "items": {
-            "anyOf": [
-              {
-                "additionalProperties": false,
-                "description": "Webhook payload for Airflow DAG run completion notifications.",
-                "properties": {
-                  "dagId": {
-                    "type": "string"
-                  },
-                  "dagRunId": {
-                    "type": "string"
-                  },
-                  "integration": {
-                    "const": "AIRFLOW",
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "integration",
-                  "dagId",
-                  "dagRunId"
-                ],
-                "type": "object"
-              }
-            ]
-          },
-          "type": "array"
-        },
-        "environment": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "environmentOverrides": {
-          "anyOf": [
-            {
-              "additionalProperties": {
-                "description": "A typed environment variable value.",
-                "properties": {
-                  "type": {
-                    "enum": [
-                      "string",
-                      "int",
-                      "bool",
-                      "integration_credential",
-                      "dict",
-                      "list"
-                    ],
-                    "type": "string"
-                  },
-                  "value": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "boolean"
-                      },
-                      {
-                        "type": "integer"
-                      },
-                      {
-                        "type": "number"
-                      },
-                      {
-                        "additionalProperties": true,
-                        "type": "object"
-                      },
-                      {
-                        "items": {},
-                        "type": "array"
-                      }
-                    ]
-                  }
-                },
-                "required": [
-                  "type",
-                  "value"
-                ],
-                "type": "object"
-              },
-              "type": "object"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "retryFromFailed": {
-          "default": false,
-          "type": "boolean"
-        },
-        "runInputs": {
-          "anyOf": [
-            {
-              "additionalProperties": true,
-              "type": "object"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "taskIds": {
-          "anyOf": [
-            {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "versionNumber": {
-          "anyOf": [
-            {
-              "type": "integer"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        }
-      },
-      "type": "object"
-    },
-    {
-      "type": "null"
-    }
-  ]
-}

addedInput schema / properties / branch

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedInput schema / properties / ciRunId

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedInput schema / properties / commit

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedInput schema / properties / continueDownstreamRun

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedInput schema / properties / data

Added value: +{
+  "default": [],
+  "items": {
+    "anyOf": [
+      {
+        "additionalProperties": false,
+        "description": "Webhook payload for Airflow DAG run completion notifications.",
+        "properties": {
+          "dagId": {
+            "type": "string"
+          },
+          "dagRunId": {
+            "type": "string"
+          },
+          "integration": {
+            "const": "AIRFLOW",
+            "type": "string"
+          }
+        },
+        "required": [
+          "integration",
+          "dagId",
+          "dagRunId"
+        ],
+        "type": "object"
+      }
+    ]
+  },
+  "type": "array"
+}

addedInput schema / properties / environment

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedInput schema / properties / environmentOverrides

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "description": "A typed environment variable value.",
+        "properties": {
+          "type": {
+            "enum": [
+              "string",
+              "int",
+              "bool",
+              "integration_credential",
+              "dict",
+              "list"
+            ],
+            "type": "string"
+          },
+          "value": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "integer"
+              },
+              {
+                "type": "number"
+              },
+              {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              {
+                "items": {},
+                "type": "array"
+              }
+            ]
+          }
+        },
+        "required": [
+          "type",
+          "value"
+        ],
+        "type": "object"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedInput schema / properties / retryFromFailed

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

addedInput schema / properties / runInputs

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedInput schema / properties / taskIds

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedInput schema / properties / versionNumber

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

First observedv0.1.0Sep 26, 2026

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds substantial non-obvious behavior: the fallback that any JSON body still starts a run with defaults, how `requestBodyMessage`/`requestBodyErrors` report that, the 64 KiB truncation limit, and the `${{ outputs.payload }}` aliasing available to task conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and identification rule, and the follow-on sentences about body handling and the payload alias each carry distinct, non-redundant information. Slightly dense in the payload-templating sentence but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values needn't be explained, and annotations cover the safety profile. The description covers the main call paths (Git vs Orchestra vs raw webhook) but leaves a meaningful chunk of the 13-parameter surface undocumented, so it is not fully complete for this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 15%, so the description carries the burden. It explains `branch`, `commit`, `versionNumber`, and `runInputs` well, but 13 parameters exist and several (`ciRunId`, `taskIds`, `environment`, `environmentOverrides`, `continueDownstreamRun`, `retryFromFailed`, `data`) get no mention, leaving the low-coverage surface only partially compensated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ("Start a pipeline run") and immediately clarifies the two ways to identify the pipeline (alias or ID). An agent can distinguish it from cancel_pipeline_run, list_pipeline_runs, and get_pipeline_run_status without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear guidance on which body fields to use per pipeline type (`branch`/`commit` for Git-backed, `versionNumber` for Orchestra-backed, `runInputs` for input values) and notes all body fields are optional. It stops short of naming alternative tools or when not to use this one, so not a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server