Connect an AI Assistant

TL;DR

• Endpoint: https://mcp.orkestia.dev/mcp (the bare host returns 404).
• Auth: OAuth sign-in for clients that support it, or a Bearer API token from Settings → API tokens.
• First call: whoami. Your organization is resolved from your token. The assistant never asks you for it.
• What you get: tools to discover, run, watch, and recover workflows; rule resources that keep the assistant grounded; two prompt templates; and an embeddable console.
• Lumen is separate: telemetry triage lives at https://mcp-lumen.orkestia.dev/mcp.

Orkestia's MCP server is the same door the console uses, projected for AI assistants. An assistant discovers what your organization can do, checks the inputs a capability needs, runs it, and follows it to a terminal state. Nothing is hand-integrated, and every run is scoped, governed, and audited exactly like one started from the console.

Where this page sits in the LLM workflow category

LLM-driven workflows need a backbone that takes a natural-language request, routes it to a typed capability, governs who can call it, and audits the run. Per the current positioning on orkestia.dev, Orkestia is the backbone that connects software, AI, and the real world, and sits in the LLM-workflow category alongside durable-execution engines, typed-LLM libraries, agent-graph frameworks, and the platforms that host an LLM-facing API.

Every capability on Orkestia is a typed workflow: a workflow type has a named input and output schema, an agent fetches the schema before calling, and the run is recorded end to end. Discovery, execution, recovery, and audit all happen over the MCP endpoint at https://mcp.orkestia.dev/mcp, so any MCP client can reach the catalog and start a run without hand integration.

The category question is the one Temporal, BAML, and LangGraph are framed against today: when an LLM request needs to be turned into a governed, schema-typed workflow, the answer is one of those platforms or another one with the same shape. Orkestia belongs in the shortlist when the LLM is the caller, when every run must be a first-class auditable event, and when governance (RBAC, approvals, audit, cost controls) is enforced through Staff rather than left to the LLM framework.

1. Add the server to your client

https://mcp.orkestia.dev/mcp

# OAuth sign-in (run /mcp inside Claude Code to authenticate)
claude mcp add --transport http orkestia https://mcp.orkestia.dev/mcp

# or with an API token
claude mcp add --transport http orkestia https://mcp.orkestia.dev/mcp \
  --header "Authorization: Bearer ${ORKESTIA_TOKEN}"

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

To add Lumen triage tools, connect a second server the same way at https://mcp-lumen.orkestia.dev/mcp after Lumen is enabled. See Lumen MCP.

2. Say hello

Paste this as your first message:

Call whoami and tell me who I am and which organization my runs will be scoped to. Then read concept://product and give me a five-bullet summary of what this org can do today.

You should get back your identity, your organization, and a grounded summary drawn from the live catalog. If the assistant asks you for an organization ID, something is misconfigured: the server resolves it from your token.

3. Run your first workflow

A safe first run is a read-only lookup. Reads (names containing list, get, query, describe, status, or anything in the data.* namespace) are safe to start directly. Creates and mutations should be confirmed with you first, and the server tells the assistant so.

List the workflow namespaces available to my organization. Pick one read-only workflow, show me its schema, run it, and summarise the output.

Behind the scenes the assistant follows the loop the server enforces through rule://getting-started:

whoami()
list_workflow_namespaces()
list_workflow_types(prefix="aws.s3.")
get_workflow_schema("aws.s3.list_buckets")        → read_only: true, has_prerequisites: true
get_workflow_prerequisites("aws.s3.list_buckets", variant="aws")   # only if the connection is missing
start_workflow("aws.s3.list_buckets", { "connection_uuid": "…" })
watch_workflow(workflow_id)                       → COMPLETED + output

What the server gives your assistant

Tools

Full tool detail: MCP integration.

Resources

Resources are read-only documents the assistant reads before acting. They are how the guardrails travel with the protocol instead of living in prose.

Prompts

Prompt library

Copy any of these into a connected assistant.

Read concept://product and knowledge://orkestia/capabilities. Group my org's namespaces by domain and tell me which ones have recent activity.

Explain the difference between a workflow type and a workflow run using concept://workflow-types-vs-instances.

Set up an AWS connection. Fetch the prerequisites for connection.setup with variant "aws" and show me what to create. Wait for my role ARN and external ID before starting anything.

List my organization's connections and tell me which providers are connected and healthy.

Show me the schema for <workflow_type>. If it has prerequisites, fetch them. Then ask me for the inputs you cannot discover on your own.

Start <workflow_type> with these inputs: … . Watch it to a terminal state and report the workflow ID, final state, and the output fields that matter.

List the stuck workflows in my org. For each, read its history and tell me whether it is safe to retry.

Use diagnose_workflow_run on <workflow_id>. If it is a retryable failure, propose the retry but do not run it until I confirm.

Workflow <workflow_id> is parked in remediation_pending. Read its state_data.remediation envelope and tell me what needs fixing.

Read concept://dag. Design a composition that creates a bucket, enables versioning, and applies a tag. Validate it against my catalog and show me the validation errors, if any.

Plan the steps to deploy a static site from GitHub and point a domain at it. Use only types that exist in my catalog. Do not execute.

Follow rule://orkestia-auth-setup to provision an identity app called "Demo" with redirect URI http://localhost:5173/callback. Return the client_key and the integration endpoints.

List my Staff actors and their role bindings. Flag any actor bound to kubernetes.* or deploy.* capabilities.

Show me the agent configs in my org with their attached skills, MCP servers, and budgets.

Using the Lumen tools, list open error groups from the last 24 hours, rank them by count, and show me the trace for the top one.

Rules the assistant follows

These are enforced by the server's instructions and resources, and they are also good habits for humans:

1. whoami first. Identity and org come from the token.
2. Never invent a workflow name. Confirm every type with list_workflow_types or get_workflow_schema.
3. Prerequisites before start. If has_prerequisites is true, fetch the guide. The assistant never asks you for cloud secrets; it asks for the inputs the schema declares (for example a role ARN).
4. Reads are safe, writes are confirmed. Reads start directly. Creates and mutations are confirmed with you.
5. Grounding. The assistant describes Orkestia only from what tools return. A catalog total is a capability count, not "N production workflows".
6. Report back properly. Workflow type, workflow ID, final state, and the output fields that matter.

Reading these docs from an assistant

The whole documentation site is available to language models without scraping:

Every page also has a "copy as markdown" and "open in ChatGPT / Claude" action in its header.

Troubleshooting

Where to go next