The OrchStep MCP server for agents

There are two ways an agent can drive OrchStep. It can shell out to the orchstep binary and parse the text. Or it can call OrchStep as a set of native tools over the Model Context Protocol, with structured arguments and structured responses. The second way is what the MCP server is for.

One command starts it:

orchstep mcp serve

Now any MCP-aware agent — Claude Desktop, a custom client, whatever you've built — sees OrchStep as a tool provider and can run tasks, inspect plans, manage modules, and generate new workflows without you gluing together string parsing.

The tools it exposes

The server presents OrchStep functionality as a small, focused set of tools:

Every response comes back as JSON, not as text the agent has to scrape. When orchstep.run finishes, the agent gets a status, a duration, and a steps array with per-step outputs — exactly the shape a model can branch on.

The workflow it runs

The tools operate on a normal workflow file. Nothing about MCP changes the YAML; it just gives the agent a clean way to call into it. Here is a workflow an agent might list_tasks and then run:

name: api
defaults:
  target: staging
tasks:
  deploy:
    steps:
      - name: build
        func: shell
        do: echo "building api"
      - name: rollout
        func: shell
        do: echo "rolling out to {{ vars.target }}"
  health:
    steps:
      - name: check
        func: shell
        do: echo "checking {{ vars.target }} health"

The agent doesn't need to know the task names in advance. It calls orchstep.list_tasks, sees deploy and health, then calls orchstep.run with the one it wants:

{
  "tool": "orchstep.run",
  "arguments": {
    "task": "deploy",
    "vars": { "target": "production" },
    "format": "json"
  }
}

And gets back something it can reason about directly:

{
  "task": "deploy",
  "status": "success",
  "duration": "2.1s",
  "steps": [
    { "name": "build", "status": "success" },
    { "name": "rollout", "status": "success" }
  ]
}

Useful patterns

A few flows the server is built for:

• Validate before running. Call orchstep.lint first; if it comes back clean, call orchstep.run. The agent catches a broken workflow before it executes a single step.
• Discover and run. Call orchstep.list_tasks to learn what's available, then run the right task instead of guessing a name.
• Generate, lint, run. Call orchstep.workflow_generate with a description, lint the result, then run it — scaffolding new automation end to end.
• Module-based. Search the registry with orchstep.module_search, install with orchstep.module_install, then run the module's tasks.

When a run fails, the error code tells the agent what to do next: TASK_NOT_FOUND means call list_tasks; VALIDATION_ERROR means call lint for detail; VARIABLE_ERROR means a required var was missing. The agent recovers without you writing recovery logic.

Wiring it into a client

For Claude Desktop, point an MCP server entry at the binary:

{
  "mcpServers": {
    "orchstep": {
      "command": "orchstep",
      "args": ["mcp", "serve"],
      "cwd": "/path/to/project"
    }
  }
}

That's the whole setup. The agent now has OrchStep as a first-class tool surface.

Where to go next

• MCP Server — full tool reference, parameters, and error codes
• Skills — the orchstep-mcp-integration skill that teaches agents these tools
• LLM Agent Integration — the bigger picture of agents and OrchStep

Already running an MCP client? Add the orchstep mcp serve entry above and your agent can run real workflows on the next turn.