---
title: "Automation"
description: "Use OpenTofu's native cloud protocol, the frozen v1 REST API, or the audience-bound MCP tool catalog."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.stackship.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Automation

StackShip has three distinct programmable surfaces today.

| Surface | Use it for | Authentication |
| --- | --- | --- |
| OpenTofu native cloud | Planning, applying, locking, and state migration through `/api/v2` | OpenTofu OAuth or a scoped service-account token; managed attempts use an internal attempt credential |
| Native v1 REST API | The dashboard control plane | Authenticated session with an active organization |
| MCP server | Agent-operated reads and scoped writes over the v1 contract | OAuth 2.1 token bound to the MCP resource |

The separate StackShip CLI is a roadmap item and is not available in private
beta. Use `tofu` for infrastructure operations and the dashboard for human
control-plane work.

## OpenTofu cloud protocol

StackShip implements the native cloud/TFE-compatible contract required by
OpenTofu. It does not ask customers to configure the generic HTTP backend.
OpenTofu resolves an organization and workspace through the standard cloud
protocol, while StackShip independently authorizes the live credential and its
tenant boundary.

Managed execution never receives the customer's OAuth or
service-account credential. StackShip injects a separate opaque `rat_`
credential through `TF_TOKEN_stackship_run` for the exact active attempt. That
credential is not a customer API key: it cannot create runs, perform recovery,
or authenticate to MCP.

Supported execution versions are exact, not ranges: any stable OpenTofu
release from `1.6.0` up, including releases newer than the StackShip
deployment. `GET /v1/toolchains/opentofu/versions` lists the current upstream
stable releases and marks which already have an immutable toolchain pin.

Service discovery also advertises `modules.v1`, the standard module registry
protocol. `tofu init` resolves private modules from the
[module registry](/registry) with the same hostname-selected credential the
cloud contract already uses.

## Native v1 API

The dashboard consumes the committed OpenAPI 3.1 contract through the generated
`@stackship/api-client`. JSON operations are exact-schema validated. Logs,
state, and run artifacts remain streams through the Worker boundary.

The v1 surface covers projects, workspaces, runs, review decisions, state
history and downloads, workspace variables, audit inventory, policies, GitHub
source settings, private module registry management, cloud credential
profiles, and OpenTofu service accounts.

See [v1 REST API](/automation/api) for the exact path inventory and request
rules.

## MCP

The MCP server is OAuth protected and fails closed on issuer, signature,
expiry, audience, or scope mismatch. It publishes the full read catalog —
projects, workspaces, runs, review evidence, logs, state history, variables,
audit, policy, GitHub sources, the module registry, credential metadata, and
toolchains — to `mcp:tools`, and narrowly scoped write tools — run creation,
binding-exact approval and rejection, cancellation, workspace and variable
writes, policy attachment and soft override, and registry module lifecycle —
to tokens that additionally carry `mcp:write`. Destructive operations,
credential secrets, and step-up-gated downloads are not published and are
refused by the API for MCP credentials.

See [MCP server](/automation/mcp) for the complete catalog and rules.

## Roadmap boundaries

The following roadmap capabilities are not available today:

- Roadmap: a StackShip-specific command-line binary, not available today;
- customer webhooks or general notification delivery;
- scheduled drift automation;
- customer-operated execution agents; and
- destructive MCP tools, including deletes, revocations, and apply recovery.

Source: https://docs.stackship.run/automation/index.mdx