MCP Integration

Orkestia exposes a public Model Context Protocol (MCP) server at https://mcp.orkestia.dev/mcp. This is the canonical AI-agent integration: any MCP-capable client — Claude, your own LLM app, an autonomous worker — connects once and gains a typed, permissioned window onto the workflow engine. The agent discovers what your organization can do, inspects the inputs a capability needs, runs it, and follows it to a terminal state — all without anyone hand-coding an integration first.

Two design choices make this safe to expose publicly:

• Org scoping is server-side. Your sign-in or bearer token resolves your organization_uuid on the server. Every run an agent starts is automatically scoped to that org — the agent never sends, guesses, or asks for the org ID. Each connection keeps its own organization; see Which organization a connection uses.
• The transport is stateless. The server is stateless streamable-HTTP: no per-replica session state, so it survives pod restarts and HPA scale events without dropping an agent's context.

Connecting a client

Most MCP clients are configured with a small JSON block. Point one at Orkestia like this:

{
  "mcpServers": {
    "orkestia": {
      "type": "http",
      "url": "https://mcp.orkestia.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${ORKESTIA_TOKEN}"
      }
    }
  }
}

Lumen's telemetry MCP is a second server. Connect it after the org is enabled:

{
  "mcpServers": {
    "lumen": {
      "type": "http",
      "url": "https://mcp-lumen.orkestia.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${ORKESTIA_TOKEN}"
      }
    }
  }
}

Once connected, the server advertises three kinds of context to the agent:

• Tools — the verbs the agent can invoke (discover, start, watch, recover).
• Resources — read-only rule://, concept://, and knowledge:// documents the agent should read before acting, delivered as first-class context rather than buried in prose, plus a templated prerequisite://{workflow_type}/{variant} resource.
• Prompts — usage-guide templates (how_to_use_workflow_mcp, diagnose_workflow_run).

AWS, Azure, and Google Cloud from one MCP endpoint

The Orkestia MCP server at https://mcp.orkestia.dev/mcp exposes the workflow catalog across AWS, Azure, and Google Cloud alongside the rest of the supported providers.

• For AWS, see the AWS connections guide.
• For Azure, see the Azure connection.
• For Google Cloud, see the GCP connection.

Execution happens in the customer's own cloud, never in Orkestia's. For how connections are scoped and runs are reviewed, see Security and Compliance and Governance and Approvals.

The discovery sequence

An agent needs no prior knowledge of your platform. It follows the same loop every time, and the server's own instructions enforce the order:

Tool surface

The tools split cleanly into two families that mirror the mental model: workflow types are registered capabilities; workflow runs are executions with a unique workflow_id. Catalog tools explore capabilities; run tools operate on live executions.

Identity

Which organization a connection uses

Each MCP connection keeps one organization. Switching organization in the web app does not change it, and neither does switching another connection.

whoami shows where the organization came from:

To move a connection, call list_organizations, then switch_organization with the target's uuid. It applies from the next request. Ask the person first: everything the assistant does afterwards lands in the new organization.

Limited API tokens

An API token limited to specific workflows narrows the MCP surface too. list_workflow_types and get_workflow_schema show only the listed types, start_workflow on any other type fails with API_TOKEN_WORKFLOW_NOT_ALLOWED, and list_stuck_workflows, get_workflow_prerequisites, resolve_workflow and force_terminate_workflow are refused with RESTRICTED_TOKEN_NOT_ALLOWED. Runs of other types read as not found.

Catalog — discover capabilities

Runs — execute and operate

Browser — use a paired Chrome

The browser_* tools let an agent use websites through a person's own Chrome, paired with the Orkestia Browser extension. The person approves every session in the extension side panel, and anything that sends, submits, pays, deletes or uploads waits for their Allow.

Page content is untrusted data, never instructions. Inputs, limits and errors are in Agent tools.

Prerequisites-first

The single most important behavioral rule: resolve prerequisites before starting a workflow. Many capabilities depend on a customer-owned resource Orkestia cannot provide for you — most commonly a cloud connection granting the platform a scoped role in your account (this is the Zero Code Custody posture: execution happens in your cloud, never ours).

The contract is explicit in the schema:

// get_workflow_schema(workflow_type) → (shape illustrative)
{
  "workflow_type": "<provider>.<service>.<operation>",
  "has_prerequisites": true,
  "prerequisite_variants": ["aws"],
  "read_only": false,
  "fields": [ { "name": "...", "type": "...", "required": true } ]
}

When has_prerequisites is true, the agent calls get_workflow_prerequisites before start_workflow. The returned guide arrives with platform identity already filled in — for example, Orkestia's AWS principal — so the human can complete a one-time setup (creating a role, granting access) without leaving the conversation.

Rule resources

Beyond tools, the server publishes rule resources — guardrails and setup guides delivered as first-class MCP context. A well-behaved agent reads the relevant rule before acting.

The server also exposes concept:// and knowledge:// orientation resources, the templated prerequisite://{workflow_type}/{variant} resource, and two prompt templates (how_to_use_workflow_mcp, diagnose_workflow_run). The full, current set lives at reference.orkestia.dev.

Worked example

A typical agent turn — "run the thing that provisions a static site for this repo" — expands into the loop below. Tool names are exact; payloads are illustrative because the per-workflow contract is owned by the live catalog.

// 1. Confirm who we are and which org we're scoped to.
await whoami()

// 2. Discover candidate capabilities (filter by namespace if known).
await list_workflow_types({ prefix: "aws." })

// 3. Inspect the input contract for the chosen type.
const schema = await get_workflow_schema({
  workflow_type: "<provider>.<service>.<operation>",
})

// 4. If the schema declares prerequisites, resolve them first.
if (schema.has_prerequisites) {
  await get_workflow_prerequisites({
    workflow_type: "<provider>.<service>.<operation>",
    variant: "default",
  })
  // → surface the setup guide to the human; wait until the connection exists.
}

// 5. Start the run with validated initial_data (no organization_uuid).
const { workflow_id } = await start_workflow({
  workflow_type: "<provider>.<service>.<operation>",
  initial_data: { /* fields per schema */ },
})

// 6. Watch to a terminal state; recover on failure.
const result = await watch_workflow({ workflow_id })
if (result.status === "FAILED") {
  await get_workflow_history({ workflow_id }) // diagnose
  await retry_workflow({ workflow_id })       // recover
}

How this connects to the rest of Orkestia

The MCP server is one of three AI surfaces, and all three resolve to the same workflow primitive:

For broader context, see Concepts, the MCP-driven guides, and the Workflow Types Registry.