AgentPrism Workflows MCP server
Commit Nov 13, 2026Run dynamic multi-agent workflow scripts using agent, parallel, and pipeline primitives over various ACP backends.
Also known as agentprism/agentprism-workflows
- Stars
- 7
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- Apache-2.0
What is AgentPrism Workflows MCP?
AgentPrism Workflows runs dynamic multi-agent workflow scripts using agent, parallel, and pipeline primitives over various ACP backends.
Summary generated from the project's README
About AgentPrism Workflows MCP server
Developers can orchestrate complex, multi-agent operations by writing JavaScript scripts that utilize agent, parallel, and pipeline primitives. This system functions as a deterministic engine that executes workflows across various Agent Client Protocol backends, including Claude Code, OpenAI Codex, OpenCode, and pi. It is available as a TypeScript SDK for custom programs or as a stdio MCP server that exposes a workflow tool to hosts like Claude Code or Zed.
Instead of reimplementing agent loops, the engine drives existing coding agents, inheriting their specific tool loops, permissions, and context management. Users can specify different backends for individual steps within a single script, such as using one model for implementation and another for verification. The system supports durable runs through journaling and checkpointing, allowing users to resume interrupted tasks using a specific run ID. It also provides git-worktree isolation to ensure that experimental agent edits do not interfere with the local filesystem.
What you can do with it
- 1Automated feature implementation and verificationDirect an agent to implement a feature through sequential stages where one model writes code and another verifies it through builds and tests.
- 2Parallelized code auditing and experimentationRun an audit of an API and a separate worker fix in isolation simultaneously to compare results.
- 3Resuming interrupted long-running workflowsContinue a previously started workflow from a specific point using its unique identifier after a provider quota limit is hit.
- 4Generating structured data from agentsRequest that an agent returns a validated object according to a specific schema rather than raw text.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableagentprism/agentprism-workflows is public and reachablegithub.com/agentprism/agentprism-workflows ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/agentprism/agentprism-workflows ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAgentPrism Workflows
Run dynamic, multi-agent workflow scripts — agent(), parallel(), pipeline() — over real coding agents (Claude Code, OpenAI Codex, OpenCode, and pi), with deterministic journaling, resume, and git-worktree isolation.
Your agent authors a small JavaScript script (export const meta, then call agent() / parallel() / pipeline()); the engine runs it in a sandboxed realm, fanning each agent() call out to an Agent Client Protocol (ACP) backend. It's available two ways:
- As a TypeScript SDK —
@automatalabs/workflows— embed the runner in your own program. - As a stdio MCP server —
@automatalabs/mcp-server, built on the SDK — expose theworkflowtool to any MCP host (Claude Code, Zed, …).
All nine
@automatalabs/*packages are published on npm — see Install. Two are primary workflow entry points: the@automatalabs/workflowsSDK and the@automatalabs/mcp-serverstdio server.@automatalabs/acp-serveris the extension-aware ACP aggregation entry point.
Why AgentPrism
Real harnesses, driven over an open protocol
Each agent() call runs on a shipped coding agent — Claude Code, Codex, OpenCode, or pi — driven over ACP, rather than a reimplementation of an agent loop around raw model APIs. You get each backend's own tool loop, permissions, and context management, plus the auth you already have on your machine (~/.claude/.credentials.json, ~/.codex/auth.json, opencode auth login, provider API keys, or pi's ~/.pi/agent/auth.json). When the harness improves, your workflows improve with no code change here.
Many agents, one workflow
The backend is chosen per agent() call: a claude/opus[1m] review step, a codex/gpt-5.6-sol implementation step, an opencode/zai/glm-5.2 planning step, a backend-default pi research step, and a custom browser QA agent can share one script, hand each other structured results, and be swapped independently. Any ACP server registers as a named backend — the built-ins are defaults, not a boundary.
Have your agent write the workflow
You describe the workflow in plain language; your agent designs it with the right APIs, validates it, and runs it. The connected MCP server is self-documenting:
- Agent Skills over MCP — the server advertises the version-matched
agentprism-workflow-authoringskill through SEP-2640. Skills-aware hosts expose its name and description first, then loadSKILL.mdand only the referenced files needed for the task. - MCP prompt — prompt-capable hosts also expose
author-workflow(optionaltask). It frames the task and directs the assistant to activate the workflow-authoring skill without injecting the guide.
A representative ask:
Implement the feature described in docs/my-feature.md as a robust workflow of sequential stages. For each stage, have gpt-5.6-sol implement at xhigh effort and claude opus verify it at xhigh — it should re-run the builds and tests itself instead of trusting the implementer's claims — with the two going back and forth until the stage is green. Then a single final review phase that returns its findings; the workflow shouldn't loop back at all once it reaches the final review. Validate the workflow before launching it, then run it in the background and see it through to the end.
From an ask like that, the agent picks the primitives — gate() fix-loops with the reviewer's feedback threaded into fresh attempts, structured-output verdicts, self-contained prompts, per-call model routing and effort via configOptions — and the validator (static parse → mock dry run → per-harness config probe) proves the script's structure and its model/config choices for zero tokens before any real run.
Durable runs — same-ID continuation
Scripts run in a deterministic realm and every agent() and checkpoint() result is journaled.
MCP { action:"resume", runId } continues that exact run ID with its args, immutable routing
inputs, journal, event stream, cumulative usage, and durable checkpoint decisions. The script is
re-read from the run's file: an edited file continues as a validated revision whose unchanged calls
replay and whose edited calls run live. It never creates a child execution or accepts args replay.
Exact journal hits rebuild state without current provider usage. Provider quota and authentication
walls pause the run; an eligible interrupted ACP call can reattach to the recorded session and
charge only new usage.
The host atomically persists format-3 immutable routing admission before live dispatch. Each actual call must resolve a model; configured calls on branches unseen by mock validation are allowed. Continuation reuses captured tiers and named-agent definitions without file drift. Old admissions remain inspectable but cannot execute. Checkpoint answers are first-writer-wins under the run lease: identical repeats are idempotent and conflicts cannot replace the durable first answer.
Compact reader/experiment fan-out:
const [audit, experiment] = await parallel([
() => agent("Audit src/api without changing files.", {
label: "audit:api", model: "codex",
}),
() => agent("Try the worker fix in isolation; return a unified diff.", {
label: "try:worker", model: "codex", isolation: "worktree",
}),
]);
The worktree's edits are discarded; return them as data. Both completed calls replay from their journal identity without a filesystem-safety annotation.
Structured output as validated objects
agent({ schema }) returns a schema-validated object, not text to parse. Claude and Codex use their agent-specific schema channels. Pi, OpenCode, and eligible custom ACP agents get a client-hosted StructuredOutput MCP tool injected automatically when they advertise HTTP MCP support. The runner still validates and re-prompts on mismatch, so the same API works for schema channels, tool capture, and validated final-text fallback.
The full ACP spec, enforced by the build
Every client-side ACP method is served (fs/*, terminal/*, permission requests, elicitation, MCP-over-ACP) and the agent-side surface — session modes, session lifecycle, auth/providers — is driven, not stubbed. A coverage manifest keyed off the SDK's method constants breaks the build on protocol drift; the separate executable extension matrix tracks vendor _session/steering support without misclassifying it as standard ACP. The end-to-end suite covers real Claude, Codex, OpenCode, and pi providers when gated, including a Claude/Codex native-steering smoke, plus a credential-free pi leg through pi-acp's injected runtime.
Controls for unattended runs
Per-run agent/concurrency limits, per-call git worktree isolation, retries, explicit call/run
cancellation, and checkpoint() provide control over agent work. Every unanswered checkpoint pauses
until an explicit answer arrives through an SDK callback or MCP checkpointReplies. No omitted
option, timeout, or missing UI approves it. ACP permissions remain live waits exposed by status and
answered through permissions-response. @automatalabs/agentprism-otel attaches to any
WorkflowManager for run → agent → tool traces and token, cost, and duration metrics.
How it works
One process plays two protocol roles at once: it's an MCP server (or a library) that accepts a workflow script, and an ACP client that drives one or more agent subprocesses to execute each agent() call.
your program ──or── MCP host (Claude Code / Zed / …)
│ runDynamicWorkflow(script) calls tool "workflow"
▼
┌──────────────────────────────────────────────┐
│ AgentPrism orchestrator │
│ • the deterministic engine runs the script │
│ • ACP CLIENT → drives agent servers │
└──────────────────────────────────────────────┘
│ session/new or resume/load, then session/prompt … (ACP over stdio)
▼
claude-agent-acp / codex-acp / opencode acp / pi-acp (long-lived, pooled subprocesses)
│ → real agents; paused occurrences may reopen their recorded session
The deterministic engine (sandboxed vm realm, parallel/pipeline, journal/resume, worktree isolation) is independent of how a single agent runs and of how the tool is exposed.
Requirements
- Node.js ≥ 22 and pnpm ≥ 10 (see
.nvmrc/packageManager). - A backend agent CLI, authenticated on your machine:
- Claude — via the bundled
@agentclientprotocol/claude-agent-acp; auth from~/.claude/.credentials.jsonorANTHROPIC_API_KEY(the orchestrator inherits your environment). - Codex — via
@automatalabs/codex-acp(+ the@openai/codexbinary, installed as a dependency); auth from~/.codex/auth.json. - OpenCode — supported but not bundled. Install the
opencodeCLI on PATH or addopencode-aito your own project (its platform binaries are large), then authenticate withopencode auth login. - pi — via the bundled
@automatalabs/pi-acp; auth from the selected provider's API key or pi's~/.pi/agent/auth.json.
- Claude — via the bundled
You only need auth for the backend(s) you actually call.
Install
From npm
pnpm add @automatalabs/workflows # the SDK
pnpm add @automatalabs/mcp-server # the MCP server
pnpm add @automatalabs/acp-server # the ACP aggregation server
From source (for development)
git clone <this-repo> agentprism-workflows
cd agentprism-workflows
pnpm install # installs deps + fetches backend binaries
pnpm build # tsc -b across all packages
Packages
These are the packages you interact with directly. The first two are the primary workflow entry points; the latter two expose ACP servers:
| Package | What it is |
|---|---|
@automatalabs/workflows |
The canonical public SDK — a thin facade that runs workflow scripts programmatically over the default ACP backend, and re-exports the supported engine + backend integration surface. Start here. |
@automatalabs/mcp-server |
The stdio MCP server (bin: agentprism-workflow) exposing the workflow tool (asynchronous run/resume, setup response, bounded status/result, permission response, stop, and an Apps monitor) — built on @automatalabs/workflows. |
@automatalabs/acp-server |
The extension-aware ACP proxy (bin: agentprism-acp-server) over stdio, Streamable HTTP, or WebSocket: probe every configured backend on a discovery connection, then pin each operational connection to Claude, Codex, OpenCode, pi, or a custom ACP server. |
@automatalabs/pi-acp |
The standalone stdio ACP server (bin: pi-acp) embedding the pi coding agent in-process; exact-pinned and spawned by the first-class pi backend. |
One optional integration package attaches to the SDK's manager surface:
| Package | What it is |
|---|---|
@automatalabs/agentprism-otel |
OpenTelemetry traces and metrics for a WorkflowManager; peer-depends only on @opentelemetry/api and no-ops when the host has no OTel SDK. |
The four packages below are internal building blocks. Most are composed by the SDK (@automatalabs/workflows → workflow-engine, acp-agents, shared-types); the exception is @automatalabs/codex-acp, which is spawned by acp-agents. You normally don't depend on any of them directly: @automatalabs/workflows is the public entry point for the supported orchestration surface.
| Package | What it is |
|---|---|
@automatalabs/acp-agents |
The ACP client + Claude/Codex/OpenCode/pi/custom backends (the AgentRunner implementation, connection pooling, auth/session lifecycle, structured output, permissions, usage) and the AcpAgent SDK (one dedicated process per held-open agent, forks, cold reopen). Internal — public entry is @automatalabs/workflows. |
@automatalabs/workflow-engine |
The deterministic engine: the script realm, parallel/pipeline, journal/resume, and worktree isolation. Internal — public entry is @automatalabs/workflows. |
@automatalabs/codex-acp |
The workspace fork of agentclientprotocol/codex-acp (imported with full history) — the ACP server the Codex backend spawns, baking turn-level outputSchema forwarding into its shipped dist. Consumed by @automatalabs/acp-agents as workspace:*; you never depend on it directly. |
@automatalabs/shared-types |
The AgentRunner seam + shared types the others compose against. Internal — public entry is @automatalabs/workflows. |
Dependency direction: mcp-server → { workflows, shared-types }; acp-server → acp-agents; workflows → { workflow-engine, acp-agents, shared-types }; acp-agents → { codex-acp, pi-acp, shared-types }. The SDK (workflows) is the single facade that composes the deterministic engine and the ACP backend, which meet only at the AgentRunner seam in shared-types. The engine never names a backend; the agents never know they're inside a workflow. acp-agents spawns the bundled codex-acp / pi-acp ACP servers as its Codex and pi backends.
Published ACP registry
Our independently published ACP servers are available as an ACP-format registry:
https://agentprism.github.io/agentprism-workflows/acp-registry/v1/latest/registry.json
It currently contains the extension-aware @automatalabs/acp-server router, the
@automatalabs/codex-acp fork, and the from-scratch @automatalabs/pi-acp server. Each npx
distribution is pinned to the npm latest version that CI
has verified is actually published; the GitHub Pages data workflow refreshes the registry after
successful releases and on its regular schedule.
Quickstart — SDK
Run a workflow script. The default backend is the ACP runner (createAcpRunner()), so this drives real agents and needs backend auth.
import { runDynamicWorkflow } from "@automatalabs/workflows";
const script = `
export const meta = {
name: "repo-scan",
description: "describe a repo as JSON, three ways in parallel",
phases: [{ title: "Fan" }],
};
const SCHEMA = {
type: "object",
additionalProperties: false,
required: ["repo", "fileCount"],
properties: { repo: { type: "string" }, fileCount: { type: "number" } },
};
phase("Fan");
const results = await parallel([
() => agent("Report this repo as JSON {repo, fileCount}.", { label: "a1", schema: SCHEMA }),
() => agent("Report this repo as JSON {repo, fileCount}.", { label: "a2", schema: SCHEMA }),
]);
return results;
`;
const run = await runDynamicWorkflow(script, { args: {} });
console.log(run.status); // "completed" | "paused" | "failed" | "aborted"
console.log(run.result); // [{ repo: "...", fileCount: 123 }, …] — schema-validated objects
console.log(run.tokenUsage, run.runId);
runDynamicWorkflow resolves to a terminal WorkflowRunResult even on pause/fail/abort — read run.status instead of catching. The optional fallbacks audit field records resume-continuation outcomes (kind: "continuation", reattached method or skip reason); model resolution itself emits no entries because the selected harness accepts or rejects the verbatim id. checkpointsTaken records every checkpoint resolved in that execution with its decision source (live, journal-replay, or injected). Both fields are absent when empty and do not affect routing or replay identity. To swap the backend (or stub it in tests), pass your own runner: runDynamicWorkflow(script, { runner }). For lower-level control, use WorkflowManager / runWorkflow (also re-exported from the SDK).
Run a single agent directly
import { createAcpRunner } from "@automatalabs/workflows";
const runner = createAcpRunner();
const data = await runner.run("Summarize this repo as JSON {summary}.", {
schema: {
type: "object", additionalProperties: false,
required: ["summary"], properties: { summary: { type: "string" } },
},
model: "claude/opus[1m]", // verified Claude id; use "codex/gpt-5.6-sol" for Codex
cwd: process.cwd(),
});
// data is typed/validated against the schema (a plain object, not text)
await runner.dispose(); // closes pooled backend processes
For a held-open agent with forks and cold resume, use the AcpAgent SDK from @automatalabs/acp-agents (re-exported by @automatalabs/workflows): new AcpAgent({ cwd, model: "codex/gpt-5.6-sol" }) spawns one dedicated process on first use, prompt() returns the verbatim turn, fork() seeds a parallel agent with everything committed so far, and close({ keep: true }) + AcpAgent.resume(ref) reopen it later — see docs/api.md.
AgentPrism Workflows MCP questions
What kind of workflows can I run?
You can run dynamic, multi-agent workflow scripts using agent(), parallel(), and pipeline() primitives over real coding agents.
How can I use AgentPrism Workflows with an MCP host?
You can use the @automatalabs/mcp-server package, which exposes the workflow tool to any MCP host like Claude Code or Zed.
Can I resume a workflow that was interrupted?
Yes, the server supports durable runs where you can use the resume action with a specific runId to continue an exact run.
Does it support structured output?
Yes, the agent function can return schema-validated objects rather than just text, utilizing agent-specific schema channels or injected MCP tools.