Orchestra MCP Server
OfficialThis MCP server exposes Orchestra API tools for observing pipeline health, managing pipelines and runs, triaging incidents, and administering workspace resources.
Diagnose failures:
whats_broken,diagnose, andpipeline_contextsummarize failing/warning runs, task failures, logs, parameters, and upstream status.Manage pipelines: list/get/create/update/delete, validate schemas, start/pause/move runs, migrate to Git-backed storage, and import Git-backed pipelines.
Inspect runs and tasks: list/get pipeline runs, cancel runs, list task runs, download logs/artifacts, and build lineage URLs.
Handle incidents and monitors: list/get/update incidents, merge/unmerge, mute/unmute, comment, manage incident settings, and create/reorder/update/delete monitors.
Administer integrations and workspace resources: manage integration connections, environments, assets, operations, state, audit events, and workspaces.
Use AI agents and skills: create/manage agents, attach skills and integrations, start/read/cancel agent sessions, and view token usage.
Note: destructive delete tools are registered but only run with OAuth; API-key calls are refused for those deletes.
Integrates with GitHub repositories as a storage provider for Orchestra pipelines and skills, and with GitHub Actions as a task integration, enabling git-backed pipeline management, repository/YAML path selection, branch and commit targeting, and GitHub Actions workflows.
Exposes Python as an Orchestra task integration, enabling pipelines and monitors to reference Python workloads and manage Python integration connections through the Orchestra API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Orchestra MCP Server list all my pipelines"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Orchestra MCP 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/orchestraRequired header:
Authorization: Bearer <YOUR_ORCHESTRA_API_KEY>API key location: Orchestra workspace settings
Related MCP server: Airflow MCP
Available Tools
Tool | Auth required | Purpose | Category |
| 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 |
| Yes | Deep dive on one task run: parameters, upstream task statuses, log tail and artifact filenames. | Triage |
| Yes | A pipeline's metadata, full definition, integrations, recent run outcomes and median succeeded duration. | Triage |
| Yes | Fetch a single pipeline. Provide exactly one selector: pipeline_id, alias, or repository together with yaml_path ( | Pipelines |
| Yes | List pipelines ( | Pipelines |
| Yes | Create a pipeline ( | Pipelines |
| Yes | Update a pipeline by selector ( | Pipelines |
| Yes | Delete a pipeline. Provide exactly one selector: pipeline_id, alias, or repository together with yaml_path ( | Pipelines |
| Yes | Get pipeline data ( | Pipelines |
| Yes | Start a pipeline run ( | Pipelines |
| Yes | Pause or unpause a pipeline ( | Pipelines |
| Yes | Move a pipeline to a folder ( | Pipelines |
| No | Validate pipeline schema ( | Pipelines |
| 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 ( | Pipelines |
| Yes | Import a pipeline ( | Pipelines |
| Yes | Get a pipeline run ( | Pipeline Runs |
| Yes | List pipeline runs with optional filters. status accepts comma-separated values: CREATED, QUEUED, RUNNING, SUCCEEDED, WARNING, FAILED, SKIPPED, CANCELLING, CANCELLED ( | Pipeline Runs |
| Yes | Cancel a running or queued pipeline run by its ID ( | Pipeline Runs |
| No | Build the URL of a pipeline run's lineage graph in the Orchestra UI (derived from | Pipeline Runs |
| Yes | List task runs for a pipeline run ( | Task Runs |
| Yes | List task runs ( | Task Runs |
| Yes | Get a task run ( | Task Runs |
| Yes | List incidents ( | Incidents |
| Yes | Get an incident ( | Incidents |
| Yes | Update an incident ( | Incidents |
| Yes | List an incident's timeline ( | Incidents |
| Yes | Get an external event's payload ( | Incidents |
| Yes | Merge incidents ( | Incidents |
| Yes | Unmerge incidents ( | Incidents |
| Yes | Mute an incident ( | Incidents |
| Yes | Unmute an incident ( | Incidents |
| Yes | Write to an incident's timeline ( | Incidents |
| Yes | Get incident settings ( | Incident settings |
| Yes | Update incident settings ( | Incident settings |
| Yes | List monitors ( | Monitors |
| Yes | Create a monitor ( | Monitors |
| Yes | Reorder monitors ( | Monitors |
| Yes | Get a monitor ( | Monitors |
| Yes | Update a monitor ( | Monitors |
| Yes | Delete a monitor ( | Monitors |
| Yes | List operations ( | Operations |
| Yes | List assets ( | Assets |
| Yes | Get an asset ( | Assets |
| Yes | List task run logs ( | Logs |
| Yes | Download a task run log ( | Logs |
| Yes | List task run artifacts ( | Artifacts |
| Yes | Download a task run artifact ( | Artifacts |
| Yes | Get an integration ( | Integrations |
| Yes | List integration connections ( | Integration Connections |
| Yes | Get an integration connection ( | Integration Connections |
| Yes | Update an integration connection ( | Integration Connections |
| Yes | Delete an integration connection ( | Integration Connections |
| Yes | Create an integration connection ( | Integration Connections |
| Yes | List environments ( | Environments |
| Yes | Create an environment ( | Environments |
| Yes | Get an environment ( | Environments |
| Yes | Update an environment ( | Environments |
| Yes | Delete an environment ( | Environments |
| Yes | Get integration state ( | State |
| Yes | List audit events ( | Audit |
| Yes | List workspaces ( | Accounts |
| Yes | The workspace-level Git connection (not integration-task Git credentials): whether a provider is linked, which one, and the org or instance that identifies it. | Accounts |
| Yes | List agent avatars ( | Agents |
| Yes | Create an agent ( | Agents |
| Yes | List agents ( | Agents |
| Yes | Get an agent ( | Agents |
| Yes | Update an agent ( | Agents |
| Yes | Delete an agent ( | Agents |
| Yes | List an agent's skills ( | Agents |
| Yes | Set an agent's skills ( | Agents |
| Yes | List an agent's integrations ( | Agents |
| Yes | Set an agent's integrations ( | Agents |
| Yes | Get agent token usage ( | Agents |
| Yes | List agent sessions ( | Agent Sessions |
| Yes | Start an agent session ( | Agent Sessions |
| Yes | Get an agent session ( | Agent Sessions |
| Yes | Send a message to an agent session ( | Agent Sessions |
| Yes | Read an agent session's messages ( | Agent Sessions |
| Yes | Cancel an agent session prompt ( | Agent Sessions |
| Yes | List skills ( | Skills |
| Yes | Create a skill ( | Skills |
| Yes | Get a skill ( | Skills |
| Yes | Update a skill ( | Skills |
| Yes | Delete a skill ( | Skills |
| Yes | Import a skill from git ( | Skills |
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/orchestraOther 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 syncSet 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)stagedev
(Optional) Disable destructive deletion
The delete tools are registered by default, but only run for a user signed in with OAuth to
the hosted endpoint: called with an Orchestra API key, including when running the server
locally, they are refused. To hide them, set ORCHESTRA_ENABLE_DELETE to anything other
than true (in any case) or 1 before starting the server:
export ORCHESTRA_ENABLE_DELETE="false"Run the server
python -m orchestramcp.serverThe server fetches every Orchestra OpenAPI spec on startup and exposes the operations
each API flags for the MCP. Set ORCHESTRA_OPENAPI_URL (Orchestra API),
ORCHESTRA_PLATFORM_OPENAPI_URL (Orchestra Platform API) or
ORCHESTRA_AGENTS_OPENAPI_URL (Orchestra Agents API) to point at a specific spec
(e.g. a local file) instead of the environment default. Startup fails if any spec
cannot be fetched, rather than serving a partial set of tools.
(Optional) Accept OAuth access tokens
The hosted Lambda can also accept OAuth 2.1 access tokens issued by Orchestra's authorization server, alongside API keys. Set all three variables to turn it on — with any of them unset, every bearer token is treated as an API key:
export ORCHESTRA_OAUTH_ISSUER="https://app.getorchestra.io"
export ORCHESTRA_OAUTH_JWKS_URI="https://app.getorchestra.io/oauth/jwks.json"
export ORCHESTRA_OAUTH_RESOURCE_URL="https://mcp.getorchestra.io/orchestra"The issuer is per-environment — swap app for stage or dev — and the rest of its
metadata, jwks_uri included, is published at
<issuer>/.well-known/oauth-authorization-server.
ORCHESTRA_OAUTH_RESOURCE_URL must be the MCP URL exactly as a user types it into their
client, path included: it is published as the resource of the
RFC 9728 metadata document, and it is the
audience every token is checked against. The authorization server has to serve that same
identifier — it mints a token only for a resource it is configured for, and stamps aud
with its own spelling of it. Verified tokens are forwarded to the Orchestra API unchanged.
Testing the OAuth flow locally
scripts/local_resource_server.py fronts the real Lambda handler with an HTTP socket,
so an MCP client can run the whole flow against the production code path:
ORCHESTRA_ENV=dev \
ORCHESTRA_OAUTH_ISSUER=https://dev.getorchestra.io \
ORCHESTRA_OAUTH_JWKS_URI=https://dev.getorchestra.io/oauth/jwks.json \
ORCHESTRA_OAUTH_RESOURCE_URL=https://mcp-dev.getorchestra.io/orchestra \
uv run python scripts/local_resource_server.pyclaude mcp add --transport http orchestra-local http://127.0.0.1:8788/orchestraConnecting should take you through discovery, client registration and a consent screen, after which tool calls run as your user rather than as an account-wide API key.
The resource URL is the deployed dev identifier rather than the local address, because it
has to be one the authorization server serves and one the Orchestra API accepts as an
audience — a token minted for 127.0.0.1 is refused by both. The cost is that the
metadata pointer in the 401 names the deployed host, so a client that follows it lands
somewhere this server is not; discovery then depends on the client falling back to
probing the address it connected to. Testing against a deployed environment avoids that,
and is also the only way to exercise the edge routing /orchestra/.well-known/*.
Development
Run
uv run pytestto run tests.Run
uv run ruff check .anduv 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.
Available Tools
85 toolscancel_agent_session_promptCancel an agent session promptA
Ask an agent session to stop working on a prompt, named by the promptAcceptedSequenceId its history records for it. This returns once the cancel is queued, and the history records when the prompt stops. Needs a grant to run the session's agent. Returns 404 for a session the caller cannot see, and 403 for one whose agent the caller cannot run. A session started by a user in the Orchestra UI is visible to that user alone, so an API key never sees one. Sessions started for a task run or an incident are visible to everyone in the workspace who can view the agent.
Inputs: session_id (required), promptAcceptedSequenceId (required), X-Orchestra-Account-Id.
cancel_pipeline_runCancel Pipeline RunBDestructive
Cancel a running or queued pipeline run by its ID.
Inputs: pipeline_run_id (required), body, X-Orchestra-Account-Id.
create_agentCreate an agentA
Create an agent in the workspace the credential resolves to. Prompts are Markdown, avatarPath is a path from the avatar catalog, gitEnabled needs the workspace's git connection, and llmKeyType picks whose LLM key its sessions use. Secrets are returned masked.
Inputs: name (required), secrets, avatarPath, gitEnabled, +9 more. Returns: object
create_agent_sessionStart an agent sessionA
Start a session with an agent and send it a first prompt. The agent replies asynchronously: this returns once the prompt is queued, and the reply is read from GET /sessions/{session_id}/history/messages. incidentId names the incident the session is about. With sessionMode USER, the default, the session is the caller's own, so it needs an OAuth token or a user API key, and a workspace API key gets 400. With INCIDENT it is the incident's, visible across the workspace, and an incident's open session takes the prompt instead of a new one starting. With hidden true the prompt still runs the turn, but its prompt.accepted history event is marked hidden so a client can leave it out of the conversation. Needs a grant to run the agent, and to view the incident when incidentId is set.
Inputs: prompt (required), agentId (required), effort, hidden, +5 more. Returns: object
create_environmentCreate an environmentB
Create a new environment with an initial set of variable values. The first environment created for a workspace is automatically marked as the default.
Inputs: name (required), values (required), X-Orchestra-Account-Id. Returns: object
create_incident_commentWrite to an incident's timelineA
Append a row to an incident's timeline, returning the event it wrote.
eventType says what the row records - COMMENT_ADDED (the default) for an ordinary comment, or AI_DIAGNOSIS_REQUESTED, AI_DIAGNOSIS_COMPLETED and AI_DIAGNOSIS_FAILED to record the start, result or failure of a diagnosis.
agentSessionId names the Orchestra agent session behind the write. The row is then attributed to Orchestra AI and linked to that session rather than to the API key; an agent takes the id from its ORCHESTRA_AGENT_SESSION_ID environment variable. The AI_DIAGNOSIS_* types require it. A session may write several over its life, but posting the same text twice returns the row already written.
description sets the incident's description alongside an AI_DIAGNOSIS_COMPLETED or AI_DIAGNOSIS_FAILED row, and needs edit permission on the incident. It is not applied over a description a person wrote.
The timeline is append-only: nothing can edit or delete a row once it is there.
Inputs: comment (required), incident_id (required), eventType, description, +2 more. Returns: object
create_integration_connectionCreate an integration connectionA
Create a connection for an integration in the caller's workspace. parameters must match the integration's authSchema, as returned by Get an integration. allowedEnvironmentIds restricts the connection to pipelines in those environments, and needs environment edit permission on every environment left out; omit it to allow every environment. Secret parameters are obfuscated in the response. OAuth integrations return a redirectUrl instead and need a user's credential.
Inputs: parameters (required), integration (required), connectionName (required), callbackPath, +4 more. Returns: object
create_monitorCreate a monitorA
Create a monitor: a rule for which failures to group into one incident, and how that incident alerts. match picks the events it claims, groupBy what makes two of them one incident, and action what happens to it - including mute, which claims the events and raises no incident or alert at all. Left out, order puts the new monitor last, so it only claims events no existing monitor claims.
Inputs: name (required), match (required), groupBy (required), order, +5 more. Returns: object
create_pipelineCreate a pipelineB
Create a new pipeline. The request body includes the pipeline definition as JSON.
Use Validate pipeline schema before creating a pipeline if you want to check the payload without saving it.
Inputs: data (required), published (required), alias, folder, +8 more. Returns: object
create_skillCreate a skillA
Create a skill from a markdown document. The markdown must open with YAML frontmatter holding the skill's name and description. Returns 409 if the workspace already has a skill with that name.
Inputs: markdown (required), X-Orchestra-Account-Id. Returns: object
delete_agentDelete an agentADestructive
Delete an agent from the workspace the credential resolves to. Agents managed by Orchestra cannot be deleted, and are refused with 403. Only runs for a user signed in with OAuth; with an Orchestra API key it is refused.
Inputs: agent_id (required), X-Orchestra-Account-Id.
delete_environmentDelete an environmentADestructive
Delete an environment entirely. The default environment cannot be deleted while other environments still exist. Only runs for a user signed in with OAuth; with an Orchestra API key it is refused.
Inputs: environment_id (required), X-Orchestra-Account-Id.
delete_integration_connectionDelete an integration connectionADestructive
Delete an integration connection from the workspace the credential resolves to, along with any agent integration mappings that use it. The default connection cannot be deleted while the integration has other connections. Only runs for a user signed in with OAuth; with an Orchestra API key it is refused.
Inputs: integration (required), connection_id (required), X-Orchestra-Account-Id.
delete_monitorDelete a monitorADestructive
Delete a monitor. Incidents it already claimed keep their link to it; new events fall through to the next matching monitor or the built-in grouping rules. Only runs for a user signed in with OAuth; with an Orchestra API key it is refused.
Inputs: monitor_id (required), X-Orchestra-Account-Id.
delete_pipelineDelete a pipeline by selectorADestructive
Delete a pipeline. Provide exactly one selector: pipeline_id, alias, or repository together with yaml_path. Only runs for a user signed in with OAuth; with an Orchestra API key it is refused.
Inputs: alias, yaml_path, repository, pipeline_id, +1 more.
delete_skillDelete a skillADestructive
Delete a skill. Skills managed by Orchestra cannot be deleted. Deleting a skill imported from git removes it from Orchestra only; the file in the repository is left as it is. Only runs for a user signed in with OAuth; with an Orchestra API key it is refused.
Inputs: skill_id (required), X-Orchestra-Account-Id.
diagnoseDiagnose Task RunARead-only
Deep dive on one failed task run: its status and messages, taskParameters and runParameters, the statuses of the upstream tasks it depends on, the tail of its newest log, and its artifact filenames. Over-long parameter values, the log tail and the artifact list are capped, and the response says which parts were cut. Use download_task_run_log or download_task_run_artifact when the tail is not enough.
Inputs: task_run_id (required), account_id. Returns: object
download_task_run_artifactDownload Task Run ArtifactARead-only
Download a task run artifact file, returned base64-encoded. Artifacts such as a dbt manifest.json are often tens of MB. At most 3MiB of file content is returned per call; fetch larger files in chunks by passing range_header (e.g. 'bytes=0-3145727') and advancing the range each call.
Inputs: filename (required), task_run_id (required), pipeline_run_id (required), account_id, +1 more.
download_task_run_logDownload Task Run LogARead-only
Download a task run log file, returned base64-encoded. At most 3MiB of file content is returned per call; fetch larger files in chunks by passing range_header (e.g. 'bytes=0-3145727') and advancing the range each call.
Inputs: filename (required), task_run_id (required), pipeline_run_id (required), account_id, +1 more.
get_agentGet an agentARead-only
Get an agent with its prompts and settings. Secrets are returned masked. Returns 404 if the agent does not exist in the workspace the credential resolves to.
Inputs: agent_id (required), X-Orchestra-Account-Id. Returns: object
get_agent_sessionGet an agent sessionARead-only
Get an agent session by ID. Returns 404 for a session the caller cannot see, and 403 for one whose agent the caller cannot view. A session started by a user in the Orchestra UI is visible to that user alone, so an API key never sees one. Sessions started for a task run or an incident are visible to everyone in the workspace who can view the agent.
Inputs: session_id (required), X-Orchestra-Account-Id. Returns: object
get_agent_session_history_messagesRead an agent session's messagesARead-only
Read a page of an agent session's messages, a whole number of complete turns at a time, oldest first. Pass exactly one of before_sequence_id or after_sequence_id. Every message carries a sequenceId of the form <unix-milliseconds>-<counter>, and sequence IDs order as strings. So before_sequence_id set to the current time in milliseconds reads the latest turns, and after_sequence_id=0 reads from the start of the session. Page back with nextBeforeSequenceId while hasPreviousPage is true, and forward with nextAfterSequenceId while hasNextPage is true. A turn still in progress is left out until it completes. Returns 404 for a session the caller cannot see, and 403 for one whose agent the caller cannot view. A session started by a user in the Orchestra UI is visible to that user alone, so an API key never sees one. Sessions started for a task run or an incident are visible to everyone in the workspace who can view the agent.
Inputs: session_id (required), turn_limit, after_sequence_id, before_sequence_id, +1 more. Returns: object
get_agent_usageGet agent token usageARead-only
Retrieve the input and output tokens spent by agent sessions in the account, summed across every agent and LLM connection, as totals for the period and in consecutive time buckets. A session counts towards the bucket it was created in.
Requires permission to view account settings.
Inputs: time_to, time_from, bucket_size, X-Orchestra-Account-Id. Returns: object
get_asset_by_idGet an assetBRead-only
Retrieve a single asset by Orchestra asset ID or external ID.
Inputs: asset_id (required), X-Orchestra-Account-Id. Returns: object
get_environmentGet an environmentARead-only
Fetch a single environment by its ID, including its variable values.
Inputs: environment_id (required), X-Orchestra-Account-Id. Returns: object
get_incidentGet an incidentARead-only
Fetch a single incident, with its merge relationships, summary counts and related resources.
Inputs: incident_id (required), X-Orchestra-Account-Id. Returns: object
get_incident_external_eventGet an external event's payloadARead-only
Fetch the raw JSON an external system sent for one row of an incident's timeline - a row whose hasExternalEvent is true. Returns 410 once the payload has expired.
Inputs: incident_id (required), incident_event_id (required), X-Orchestra-Account-Id. Returns: object
get_incident_settingsGet incident settingsARead-only
Get the workspace's incident settings: whether incidents are on, which failures can raise one, and how incidents alert. A workspace that has never saved its settings gets the defaults.
Inputs: X-Orchestra-Account-Id. Returns: object
get_integrationGet an integrationARead-only
Fetch a single integration by its identifier, including its auth and job schemas. Each auth_schema item's name is a connection field, and format: password marks a secret one.
Inputs: integration (required). Returns: object
get_integration_connectionGet an integration connectionARead-only
Fetch a single integration connection in the workspace the credential resolves to, including its auth parameters. Secret auth parameters are obfuscated in the response.
Inputs: integration (required), connection_id (required), X-Orchestra-Account-Id. Returns: object
get_integration_state_for_state_awareGet integration stateBRead-only
Fetch the stored state for the given integration in the workspace the credential resolves to.
Inputs: integration (required), X-Orchestra-Account-Id. Returns: object
get_monitorGet a monitorCRead-only
Fetch a single monitor's definition.
Inputs: monitor_id (required), X-Orchestra-Account-Id. Returns: object
get_pipelineGet a pipeline by selectorARead-only
Fetch a single pipeline. Provide exactly one selector: pipeline_id, alias, or repository together with yaml_path.
Inputs: alias, branch, commit, version, +4 more. Returns: object
get_pipeline_dataGet pipeline dataARead-only
Fetch the full pipeline definition for a pipeline selected by pipeline_id or alias. Optionally specify a version, branch, or commit to load a specific revision.
Inputs: alias, branch, commit, version, +4 more. Returns: object
get_pipeline_runGet a pipeline runARead-only
Retrieve a single pipeline run by ID, including its status, however long ago it ran.
Inputs: pipeline_run_id (required), X-Orchestra-Account-Id. Returns: object
get_pipeline_run_lineage_urlGet Pipeline Run Lineage URLARead-only
Build the URL of a pipeline run's lineage graph in the Orchestra UI.
Inputs: pipeline_run_id (required). Returns: result
get_skillGet a skillARead-only
Fetch a single skill, including its full markdown.
Inputs: skill_id (required), X-Orchestra-Account-Id. Returns: object
get_task_runGet a task runARead-only
Retrieve a single task run by ID, however long ago it ran, without needing its pipeline run ID.
Inputs: task_run_id (required), X-Orchestra-Account-Id. Returns: object
get_workspace_git_connectionGet Workspace Git ConnectionARead-only
The workspace-level Git connection: whether a Git provider (GitHub, GitLab, Azure DevOps, Bitbucket) is linked to the Orchestra account itself, which one, and the org or instance that identifies it. This is the account link used for Git-backed pipelines, not the Git credentials an integration task uses (e.g. a Python or dbt task's repository connection); see list_integration_connections for those. Call it during onboarding, and again after the user links Git to confirm it.
Inputs: account_id. Returns: object
import_pipelineImport a pipelineC
Import a Git-backed pipeline definition from a repository into Orchestra.
Inputs: yamlPath (required), repository (required), defaultBranch (required), storageProvider (required), +3 more. Returns: object
import_skillImport a skill from gitA
Import a skill from a markdown file in the workspace's connected git repository, with the same frontmatter as a created skill. Skills imported from git are read-only: edit the file in the connected repository instead. Returns 422 if no git provider is connected, 404 if the file is not on the branch.
Inputs: path (required), repository (required), defaultBranch (required), X-Orchestra-Account-Id. Returns: object
list_accountsList workspacesARead-only
Lists the workspaces this credential can act on. An API key is issued to one workspace, so it lists that workspace alone. An OAuth token lists the workspaces chosen when access was granted, limited to those its user is still a member of.
Pass a returned id to select the workspace on calls that act within one (the X-Orchestra-Account-Id header in the API).
Inputs: no named parameters. Returns: object
list_agent_avatarsList agent avatarsARead-only
List the avatars an agent can use: Orchestra's stock avatars and those uploaded to the workspace the credential resolves to. Pass an entry's path as avatar_path when creating or updating an agent. url is a short-lived link to the image, and is omitted for an uploaded avatar that is still being scanned for malware.
Inputs: X-Orchestra-Account-Id. Returns: object
list_agent_integrationsList an agent's integrationsARead-only
List the integration connections an agent can use. Each integration is a connection key of the form <INTEGRATION>_<connection id>, e.g. SNOWFLAKE_my_connection. Returns 404 if the agent does not exist in the workspace the credential resolves to.
Inputs: agent_id (required), page, page_size, X-Orchestra-Account-Id. Returns: object
list_agentsList agentsARead-only
List the agents in the workspace the credential resolves to, including those managed by Orchestra, filtered to the agents the caller may view. Prompts and secrets are not included; get an agent by id for those.
Inputs: page, search, page_size, orchestra_managed, +1 more. Returns: object
list_agent_sessionsList agent sessionsARead-only
List the agent sessions in the workspace the credential resolves to that the caller can see, most recently updated first. A session started by a user in the Orchestra UI is visible to that user alone, so an API key never sees one. Sessions started for a task run or an incident are visible to everyone in the workspace who can view the agent.
Inputs: q, page, status, archived, +5 more. Returns: object
list_agent_skillsList an agent's skillsARead-only
List the skills attached to an agent, with each skill's name and description. Returns 404 if the agent does not exist in the workspace the credential resolves to.
Inputs: agent_id (required), page, page_size, X-Orchestra-Account-Id. Returns: object
list_assetsList assetsBRead-only
Retrieve a paginated list of assets for the workspace the credential resolves to.
Assets can be filtered by type, integration, integration account, workspace, database, schema, status, or asset ID. By default, results are sorted by created_in_integration in descending order.
Inputs: page, status, asset_ids, page_size, +9 more. Returns: object
list_audit_eventsList audit eventsARead-only
List the audit trail for the workspace the credential resolves to, newest first: who did what, to which resource, and what changed.
occurred_after is required and sets how far back the trail is read; every other filter narrows within that window.
Inputs: occurred_after (required), page, action, actor_id, +5 more. Returns: object
list_environmentsList environmentsARead-only
List the environments for the workspace the credential resolves to. Returns environment metadata only — fetch a single environment by ID to retrieve its variable values.
Inputs: X-Orchestra-Account-Id. Returns: object
list_incident_eventsList an incident's timelineARead-only
Fetch the timeline for a single incident, newest first. Paginated from the start - a grouped incident accumulates one event per attached failure, so the history runs to hundreds of rows well before anyone triages it.
Inputs: incident_id (required), page, page_size, X-Orchestra-Account-Id. Returns: object
list_incidentsList incidentsARead-only
List incidents for the workspace the credential resolves to, most severe first, with merged children nested under their parent.
Filters apply to top-level incidents only - a child is always returned alongside its parent, so a filtered list still shows the full incident rather than part of one. Use name to filter incidents by a case-insensitive substring match on the incident name. Use sort_column and sort_direction to sort top-level incidents by a single column instead; merged children keep the default order.
Inputs: name, page, status, severity, +6 more. Returns: object
list_integration_connectionsList integration connectionsARead-only
List the integration connections configured for the workspace the credential resolves to. Returns connection metadata only — secret auth parameters are never included in the response. Optionally filter by integration or authStatus.
Inputs: authStatus, integration, X-Orchestra-Account-Id. Returns: object
list_monitorsList monitorsBRead-only
List the workspace's monitors in evaluation order. Where two monitors claim the same event, the one with the lower order wins.
Inputs: X-Orchestra-Account-Id. Returns: object
list_operationsList operationsARead-only
Retrieve a paginated list of task operations for the workspace the credential resolves to.
From 2026-10-01 the default changed from the last 7 days to the last 24 hours. Pass time_from and time_to explicitly to control the window.
Use operation filters to narrow results by operation type, integration, external ID, operation status, or task run ID.
Inputs: page, status, time_to, page_size, +6 more. Returns: object
list_pipeline_runsList Pipeline RunsBRead-only
List pipeline runs with optional filters. status accepts comma-separated values: CREATED, QUEUED, RUNNING, SUCCEEDED, WARNING, FAILED, SKIPPED, CANCELLING, CANCELLED.
Inputs: page, status, time_to, page_size, +5 more. Returns: object
list_pipelinesList pipelinesARead-only
List pipelines for the workspace the credential resolves to.
Always pass page and page_size to receive a paginated response with page, page_size, total, and results fields, sorted by pipeline name. Use name to filter pipelines by a case-insensitive substring match on the pipeline name.
Inputs: name, page, page_size, X-Orchestra-Account-Id. Returns: object
list_skillsList skillsARead-only
List the skills available in the workspace the credential resolves to, including those managed by Orchestra. Each skill's markdown is omitted; fetch a single skill to read it.
Inputs: page, search, page_size, sync_status, +2 more. Returns: object
list_task_run_artifactsList task run artifactsARead-only
List artifacts linked to a task run, such as dbt manifest.json, run_results.json, catalog.json, semantic_manifest.json, and sources.json files. For dbt v2, dbt docs generate produces index.html, assets.zip, and info_schema.zip instead of catalog.json.
Inputs: task_run_id (required), pipeline_run_id (required), X-Orchestra-Account-Id. Returns: object
list_task_run_logsList task run logsARead-only
List log files linked to a task run. Use the returned filenames with the download endpoint.
Inputs: task_run_id (required), pipeline_run_id (required), X-Orchestra-Account-Id. Returns: object
list_task_runsList task runsARead-only
Retrieve a paginated list of task runs for the workspace the credential resolves to.
From 2026-10-01 the default changed from the last 7 days to the last 24 hours. Pass time_from and time_to explicitly to control the window.
Filter by multiple statuses, integrations, pipeline IDs, or task run IDs using comma-separated values. For example, status=SUCCEEDED,FAILED&integration=HTTP,SNOWFLAKE returns task runs matching either status and either integration.
Inputs: page, status, time_to, page_size, +6 more. Returns: object
list_task_runs_for_pipeline_runList task runs for a pipeline runARead-only
Retrieve task runs belonging to a single pipeline run. This endpoint uses page_size default 10 and maximum 50.
Inputs: pipeline_run_id (required), page, page_size, include_superseded, +1 more. Returns: object
merge_incidentsMerge incidentsA
Merge the incidents named in the request body into the incident in the path. Merging is one level deep - merging an incident that already has a parent, or naming one that has incidents merged into it, is rejected rather than nesting further.
agentSessionId is optional, and only Orchestra agent sessions should set it. When set, the merge is attributed to Orchestra AI and linked to that session, and the session may only merge the incident it was started for, into an older incident.
Inputs: incidentIds (required), incident_id (required), agentSessionId, X-Orchestra-Account-Id. Returns: object
migrate_pipelineUpdate pipeline storage settingsB
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.
Inputs: path (required), repository (required), defaultBranch (required), storageProvider (required), +4 more. Returns: object
move_pipelineMove a pipeline to a folderA
Move an Orchestra-backed pipeline to a folder by alias or pipeline ID, leaving its definition and versions as they are. A git-backed pipeline's folder comes from where its YAML file lives, so move the file instead.
Inputs: folder (required), pipeline_id_or_alias (required), X-Orchestra-Account-Id. Returns: object
mute_incidentMute an incidentA
Silence further alerts on this incident until the account's alert budget next refills. Already muted is a no-op.
Inputs: incident_id (required), X-Orchestra-Account-Id. Returns: object
pause_pipelinePause or unpause a pipelineA
Pause or unpause a pipeline by alias or pipeline ID. A paused pipeline's schedules, sensors, trigger events, and start_pipeline calls do not start new runs.
Inputs: paused (required), pipeline_id_or_alias (required), X-Orchestra-Account-Id. Returns: object
pipeline_contextPipeline ContextARead-only
What an agent needs before editing or reasoning about a pipeline: its metadata, its full definition (the pipeline YAML structure as JSON), the integrations its tasks use, its recent run outcomes, and the median duration of its succeeded runs. Takes a pipeline ID or an alias. Run history covers the last 7 days, the widest window the API serves.
Inputs: pipeline_id_or_alias (required), account_id. Returns: object
reorder_monitorsReorder monitorsA
Set the evaluation order of the workspace's monitors. monitorIds must name every monitor exactly once; each monitor's order becomes its position in the list.
Inputs: monitorIds (required), X-Orchestra-Account-Id. Returns: object
send_agent_session_messageSend a message to an agent sessionA
Send a further prompt to an agent session. The agent replies asynchronously: this returns once the prompt is queued, and the reply is read from GET /sessions/{session_id}/history/messages. Needs a grant to run the session's agent. Returns 404 for a session the caller cannot see, and 403 for one whose agent the caller cannot run. A session started by a user in the Orchestra UI is visible to that user alone, so an API key never sees one. Sessions started for a task run or an incident are visible to everyone in the workspace who can view the agent.
Inputs: message (required), session_id (required), pipelineEditorContext, X-Orchestra-Account-Id.
set_agent_integrationsSet an agent's integrationsA
Replace the integration connections an agent can use with the given list, and return the agent's integrations afterwards. An empty list removes them all. Each integration is a connection key of the form <INTEGRATION>_<connection id>, e.g. SNOWFLAKE_my_connection, and must be a connection in the same workspace; the request is refused with 404 if any is not, and with 400 if any is limited to environments the agent is not allowed.
Inputs: body (required), agent_id (required), X-Orchestra-Account-Id. Returns: object
set_agent_skillsSet an agent's skillsA
Replace the skills attached to an agent with the given list: skills not in the list are detached, and an empty list detaches them all. Each skillId must be a skill in the same workspace or one managed by Orchestra, and the request is refused with 404 if any is not; duplicates are ignored. Agents managed by Orchestra cannot have their skills changed.
Inputs: body (required), agent_id (required), X-Orchestra-Account-Id.
start_pipelineStart a pipeline runA
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.
Inputs: pipeline_id_or_alias (required), data, branch, commit, +10 more. Returns: object
unmerge_incidentsUnmerge incidentsA
Detach the incidents named in the request body from the incident in the path, restoring each as a standalone incident. The exact inverse of merge.
Inputs: incidentIds (required), incident_id (required), X-Orchestra-Account-Id. Returns: object
unmute_incidentUnmute an incidentA
Lift this incident's mute early. A no-op if it was never muted, or already lapsed.
Inputs: incident_id (required), X-Orchestra-Account-Id. Returns: object
update_agentUpdate an agentA
Update the fields given; send null to clear an optional field. A masked secret value keeps the stored secret. An Orchestra-managed agent accepts only gitEnabled, secrets, llmKeyType and allowedEnvironmentIds, which apply to this workspace alone, and refuses any other field with 403.
Inputs: agent_id (required), name, secrets, avatarPath, +10 more. Returns: object
update_environmentUpdate an environmentA
Update an environment's name, default flag, and variable values. Only the fields supplied are changed; omitted fields are left untouched. The supplied values replace the existing values in full — they are not merged. Marking an environment as the default automatically unsets the previous default environment.
Inputs: environment_id (required), name, values, defaultEnv, +1 more. Returns: object
update_incidentUpdate an incidentA
Change an incident's status, severity, name, assignee or subscribers. A field left out of the request body keeps its stored value, and sending assignee as null unassigns. An assignee or subscriber must be able to view the incident or be in the account's Slack workspace.
Returns the detail shape - a patch writes timeline rows of its own, so the caller's event count is out of date the moment the change lands.
Inputs: incident_id (required), name, status, assignee, +4 more. Returns: object
update_incident_settingsUpdate incident settingsA
Change the workspace's incident settings and return all of them. Settings left out of the body keep their current value.
Inputs: environmentIds, warningsEnabled, incidentsEnabled, autoResolveOnSuccess, +7 more. Returns: object
update_integration_connectionUpdate an integration connectionA
Update one of connectionName, isDefault: true, allowedEnvironmentIds, or parameters with credentialStore on an integration connection. parameters follow the integration's authSchema and re-authenticate the connection; send obfuscated secrets back unchanged to keep them. allowedEnvironmentIds replaces the environments whose pipelines may use the connection, an empty list allowing every environment, and needs environment edit permission on every environment whose access changes. OAuth integrations return a redirectUrl instead.
Inputs: integration (required), connection_id (required), isDefault, parameters, +6 more. Returns: object
update_monitorUpdate a monitorA
Replace a monitor's definition with the one in the body. A field left out takes its default rather than keeping its stored value, except order, which keeps the monitor's place.
Inputs: name (required), match (required), groupBy (required), monitor_id (required), +6 more. Returns: object
update_pipelineUpdate a pipeline by selectorA
Update an existing Orchestra-backed pipeline. Select it with pipeline_id or alias in the request body. Git-backed pipelines cannot be updated through this endpoint.
Inputs: data (required), published (required), alias, pipelineId, +1 more. Returns: object
update_skillUpdate a skillA
Replace a skill's markdown. Its name and description are re-read from the new frontmatter. Skills imported from git are read-only: edit the file in the connected repository instead. Skills managed by Orchestra cannot be changed.
Inputs: markdown (required), skill_id (required), X-Orchestra-Account-Id. Returns: object
validate_pipelineValidate PipelineARead-only
Validate a full pipeline definition document without creating or updating a pipeline. Use it to check a definition before create_pipeline or update_pipeline.
Inputs: pipeline_definition (required), account_id, canonicalize. Returns: object
whats_brokenWhat's BrokenARead-only
Start here for 'what is broken' or 'why did last night's run fail'. Returns every failing and warning pipeline run in the window, already joined to the task runs that failed inside it, with each task's message, externalMessage, platformLink and duration-vs-baseline anomalies. Retried attempts are excluded. Windows wider than 168 hours are clamped to that, the widest the API serves. Follow up on a single task run with diagnose.
Inputs: account_id, environment, window_hours. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 85 tools
Most tools target distinct resources and actions, and the detailed descriptions clarify boundaries between related tools like whats_broken, diagnose, and get_task_run. However, there is some overlap among pipeline retrieval tools (get_pipeline, get_pipeline_data, pipeline_context) and among task-run listing/downloading tools that could still lead to misselection in a surface this large.
The vast majority of tools follow a clear snake_case verb_noun convention (list_pipelines, create_agent, update_monitor, delete_environment). A few outliers like whats_broken, diagnose, and pipeline_context break the verb_noun pattern, but they remain readable and consistent in casing.
With 85 tools, this server is far beyond a reasonable MCP tool surface and well past the 50+ threshold for an extreme mismatch. Even for a broad orchestration platform, the volume is likely to overwhelm tool selection and increase the chance of wrong-tool calls.
Coverage is very broad across pipelines, runs, tasks, incidents, monitors, agents, skills, integrations, environments, assets, and audit events, with CRUD where appropriate. Minor gaps remain, such as no explicit pipeline-run retry, no integration catalog listing tool, and no manual incident create/delete operations.
Maintenance
Related MCP Connectors
Interact with the Stitch API using natural language commands.
Deploy, monitor, and manage your OpenClaw AI assistants via natural language.
Read your runners.io organisation's jobs, logs, test results, cache and spend from an AI agent.
Interact with your Google Cloud Composer resources using natural language commands.
Related MCP Servers
AlicenseNot gradedqualityDmaintenanceEnables interaction with Nullplatform's API endpoints for managing deployments, scopes, services, and other cloud resources through natural language using the official OpenAPI specification.1MIT- AlicenseNot gradedqualityDmaintenanceEnables users to interact with Apache Airflow orchestration platform through natural language to query pipeline statuses, troubleshoot DAG failures, trigger DAGs, and analyze configurations.11MIT
- AlicenseAqualityCmaintenanceEnables interaction with an Airbyte instance through natural language, supporting workspaces, sources, destinations, connections, jobs, logs, tags, streams, and connector definitions.3643 PyPI5Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables natural language interaction with Apache Airflow for querying DAGs, monitoring execution, and troubleshooting failures.38 PyPI1MIT