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 bearer token resolves your organization_uuid on the server. Every run an agent starts is automatically scoped to your org — the agent never sends, guesses, or asks for the org ID.
• 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

Catalog — discover capabilities

Runs — execute and operate

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.