Connect your AI tool, then run your first workflow

How to point an AI client at the Orkestia MCP server and take a run from nothing to finished: sign in, discover, read a schema, start, watch.

Orkestia16 September 20265 min read

Orkestia is the backbone that connects software, AI, and the real world. In practice that means one engine of typed workflows, and three ways to call it: the console, the API, and any AI client that speaks MCP. Whichever one starts a run, the run is the same object, with the same permissions and the same history.

This post is the shortest honest path from a fresh account to a finished run. It is written against the platform as it works today, and every tool name below is one the MCP server actually exposes.

What a workflow is here

A capability in Orkestia is not an endpoint you call and hope. It is a workflow: a declared input schema, a set of named states, and transitions that are persisted as they happen. Each transition records who ran it, when, and what came back.

Three consequences follow, and they are the whole point.

Input is checked before anything moves. A workflow declares its fields. Wrong shape, no run. You find out at the boundary, not halfway through a change to a live system.

A run has a history, not a log line. You can ask an in-flight run what state it is in, ask a finished one what it did, and retry one that failed without replaying the parts that already succeeded.

An agent is not a special case. When an AI client starts a workflow, it passes through the same access control and the same audit trail as a person clicking a button. There is no side door where automation gets to skip the governance.

Step one, an account

Create an account at app.orkestia.dev/start and subscribe. There is one published plan and every customer pays the same rates, so there is nothing to negotiate before you can try it. The full breakdown is on the pricing page.

Step two, connect the MCP server

Orkestia runs a hosted MCP server. The URL you paste into your client is:

https://mcp.orkestia.dev/mcp

Anything that speaks the Model Context Protocol over streamable HTTP can use it. Claude, Cursor, and other MCP clients all take a server URL in their configuration. In a client that reads a JSON config, the entry looks like this:

{
  "mcpServers": {
    "orkestia": {
      "url": "https://mcp.orkestia.dev/mcp"
    }
  }
}

Sign in when the client prompts you. From that point the server knows which organization you belong to, and it scopes everything you do to that organization on its own. You never pass an organization id by hand, and you should be suspicious of any instruction that asks you to.

Step three, confirm who you are

The first call to make is always the same:

whoami()

It returns the principal the server resolved from your token. Two reasons this is worth doing before anything else. It tells you the connection is real rather than merely configured. And it tells you which identity your runs are about to be recorded under, which matters on the day someone asks who did what.

Step four, find the capability

You do not need to know a workflow's name in advance. Discovery is three calls, narrowing each time.

list_workflow_namespaces()
list_workflow_types(prefix="aws.s3.")
get_workflow_schema("aws.s3.create_bucket")

list_workflow_namespaces shows you what families exist. list_workflow_types browses one of them, and takes a free-text q when you know what you want but not where it lives. get_workflow_schema is the one that matters before you run anything: it returns the input fields, which of them are required, and a read_only flag that tells you whether starting this workflow changes anything at all.

That flag is the cheapest safety rail on the platform. A read-only workflow can be started to see what it returns. Anything else deserves a second look at the schema first.

If the schema comes back with has_prerequisites: true, call get_workflow_prerequisites before you try to start it. Connections are the usual case: the workflow needs a credential to your cloud or your provider, and the prerequisite response is a setup guide with Orkestia's side of it already filled in.

You can also browse the same catalog without an account, at orkestia.dev/catalog.

Step five, run it

start_workflow(workflow_type="...", initial_data={...})

The call returns a workflow_id, which is the run, not the kind. Keep the two straight: a workflow type is a capability the platform offers, a workflow id is one execution of it that belongs to you.

From there:

Call	What it answers
`get_workflow_status(workflow_id)`	What state is it in now, and did it finish
`get_workflow_history(workflow_id)`	Every transition, with actor and timestamp
`watch_workflow(workflow_id)`	Block until it settles, for short runs
`retry_workflow(workflow_id)`	Resume a failed run from where it stopped

A run that returns a success status has not necessarily done what you assumed. Read the state data. The platform will tell you exactly what happened, which is more useful than a green tick.

Where the work actually happens

Orkestia is the control plane. The compute, the network, and the storage for your own resources stay in your own cloud account, connected once and reused by every capability that needs them. You pay your provider directly for what runs there. Credentials are held by the connection and are not handed to the thing that calls the workflow, so an agent can operate your infrastructure without ever holding a key to it.