FlowMCP

Most MCP servers wrap an entire platform: every endpoint becomes a tool, the model gets a 40-tool surface, and orchestration is outsourced to sampling — then everyone blames the model. FlowMCP inverts that: workflows are the tools. Each MCP tool is one known, named workflow; a deterministic engine executes the steps; the model's only job is picking the flow and filling 2–3 parameters. Small models (7–30B) can drive this reliably, because there is almost nothing to get wrong.

Quickstart (60 seconds)

npm install -g @petergreenappliedai/flowmcp
flowmcp serve                    # serves the demo flows over stdio
flowmcp serve --flows ~/my-flows # serves yours

Or from a clone (for development):

git clone https://github.com/PeterGreenAppliedAI/FlowMCP.git && cd FlowMCP
npm install
npm test          # hermetic — no network needed
npm start         # serves MCP over stdio

Point any MCP client at it. Claude Desktop / Claude Code / anything MCP:

{
  "mcpServers": {
    "flowmcp": {
      "command": "npx",
      "args": ["-y", "@petergreenappliedai/flowmcp", "serve", "--flows", "/absolute/path/to/your/flows"]
    }
  }
}

Your client will list two tools — morning_brief and hn_top — not forty. Both run against keyless public APIs (Open-Meteo, Hacker News), so they work on a fresh clone with zero configuration.

> morning_brief city="Lisbon"

# Morning brief — Lisbon, Portugal

## Weather today
High 29.4°C / low 19.3°C, 0% chance of rain.

## Top of Hacker News
- **…** — 330 points https://…

Related MCP server: agentloop

Flow file format

Flows are data, not code. The server loads every flows/*.flow.json5 at startup and exposes each as one MCP tool. An invalid flow is a loud startup error naming the file and field.

{
  name: 'morning_brief',          // becomes the MCP tool name (snake_case)
  description: 'WHEN TO USE: …',  // ≤300 chars — this is the model's entire manual
  input: {                        // 0–3 parameters, no more
    city: { type: 'string', description: 'City for the weather', required: false, default: 'New York' },
  },
  env: ['WEATHER_API_KEY'],       // ONLY these env vars are visible to {{env.X}} — least privilege
  steps: [ /* run in order; each result is available as steps.<id> */ ],
  output: '{{steps.render}}',     // the tool's text result
}

Check a directory without serving: npm start -- --flows ./my-flows --validate exits 0 if every flow is valid, 1 with the file and field otherwise.

Step kinds

Everything downstream of a step sees input.*, env.* (for {{env.API_KEY}} — never put secrets in flow files), and steps.<id>. A failed step aborts the flow and returns a structured isError result naming the step. Whole-flow timeout: 60s.

Writing your own flow

Drop a file in a flows directory, restart the server — that's the whole workflow. The server reads flows/ in the repo by default; point it anywhere with --flows (or the FLOWMCP_FLOWS_DIR env var), which is how you keep private flows out of a public checkout:

npm start -- --flows ~/my-flows

// flows/cat_fact.flow.json5
{
  name: 'cat_fact',
  description: 'WHEN TO USE: the user wants a random cat fact.',
  input: {},
  steps: [
    { id: 'fact', kind: 'http_request', url: 'https://catfact.ninja/fact' },
    { id: 'render', kind: 'template', template: 'Cat fact: {{steps.fact.fact}}' },
  ],
  output: '{{steps.render}}',
}

Composition: wrapping other MCP servers

Flows can call tools on other MCP servers — and this is where the thesis becomes an operation instead of an opinion. Register downstream servers in a servers.json5 next to your flow files:

Downstream servers speak either transport: stdio (command) or remote Streamable HTTP (url + headers, e.g. a hosted Shopify/Business Central MCP — tokens interpolated from env):

{
  erp: {
    url: 'https://your-tenant.example.com/mcp',
    headers: { Authorization: 'Bearer {{env.ERP_TOKEN}}' },
    attestReadOnly: ['list_customers', 'get_customer'],  // operator-attested reads (server annotates nothing)
    allow: ['post_invoice'],                       // write-capable, two-phase gated
  },
  github: {
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-github'],
    env: { GITHUB_TOKEN: '{{env.GITHUB_TOKEN}}' },  // interpolated — never inline secrets
    allow: [],                                       // non-read-only tools need explicit listing
    shell: true,                                     // Windows: npx is a .cmd shim — raw spawn can't exec it
  },
}

(shell defaults to false. On Windows, .cmd shims like npx need shell: true — or point command directly at a Node entry point. servers.json5 is operator-trusted config, so the shell opt-in is a portability knob, not an injection surface. Relative paths in command/args resolve against the directory containing servers.json5 — the config works no matter where the flowmcp process was started from.)

Then use an mcp_call step like any other:

{ id: 'issue', kind: 'mcp_call', server: 'github', tool: 'get_issue',
  args: { owner: 'x', repo: 'y', issue_number: '{{input.n}}' } }

The key property: the wrapped server's 40 tools never appear in FlowMCP's tools/list. 40 tools in, 3 workflows out — the model's surface never grows, no matter how many servers sit behind it.

Rules of engagement:

• Read-only by default, fail-closed. A downstream tool is callable only if it declares annotations.readOnlyHint: true, is operator-attested as a read in that server's attestReadOnly list (a security assertion — production servers often annotate nothing), or is explicitly named in its allow list. Naming a write tool is a consent moment, on purpose — and it changes what FlowMCP advertises: annotations are computed per flow from its steps, so a flow containing a POST or an allowlisted write tool is published with readOnlyHint: false, destructiveHint: true. FlowMCP never tells a client a write-capable flow is read-only.

• Children get a minimal environment. Downstream servers receive a baseline (PATH, HOME, …) plus the vars you configure in their env block — never the whole parent environment, unless you set inheritEnv: true for that server.

• One session per child, not per flow. Downstream servers spawn lazily on first use, stay alive across calls, respawn on crash (3 attempts, then a 5s backoff), and shut down after 5 minutes idle. The client handshakes at the newest supported protocol revision and validates what comes back.

• The step timeout covers spawn + handshake + call as one unit, bounded by the flow's 60s deadline — a slow cold-start can't invisibly eat the budget.

• Results are capped at maxResultChars (default 8K) — downstream verbosity is not your flow's problem to inherit. structuredContent is preferred when the downstream tool provides it; otherwise JSON text results are parsed so later steps can path into them.

The benchmark

The thesis is an empirical claim, so we tested it: six conditions, ten local models (4B–35B plus DeepSeek v4-flash), identical fixture data, outcome-based scoring. Headline: 79% task success through the two-flow façade vs 10% on the same 35 tools raw — paired McNemar 33 discordant pairs, every one favoring the façade (exact p ≈ 2.3×10⁻¹⁰) — at a tenth of the tokens per attempt. A 7B through the façade outscored a 35B driving the raw surface. Full report with charts, per-model tables, and everything the data does not prove: petergreenappliedai.github.io/FlowMCP · method, harness, raw results, and transcripts in bench/.

The CLI

One entry point for the whole loop (from a clone: npx tsx src/cli.ts <cmd>, or npm run build once and use node dist/cli.js; installed as a package it's the flowmcp bin):

author needs an OpenAI-compatible endpoint via --gateway or the GATEWAY env var — there is no default endpoint or model; any local or hosted model works.

The authoring loop (experimental)

"Workflows as tools" has an obvious objection: someone has to author the workflows. The answer, shipped as flowmcp author / compile / detect: a model helps author the flow once, under observation and validation — it does not improvise the workflow at runtime. A model writes a program against the tool surface; an instrumented runner records its execution (cassette record/replay for live, nondeterministic APIs); the compiler derives a candidate flow from the observed trace — dataflow classified by variant differencing, constants separated from inputs, redundant calls removed — and emits it with provenance, warnings, and fail-closed refusals for anything it cannot prove. Replay against mutated data catches hardcoding before a human ever reviews it.

The full loop exists and has run end-to-end: detect.ts nominates flow candidates from execution logs (frequency × cost × success, inputs discovered from cross-run argument variance); flowmcp author takes an intent, introspects the configured servers' read-only tools, has a model write and repair a script in a disposable sandboxed process, records it against the real servers, and compiles the trace. Dogfooded on a real recurring news-gathering workflow: the compiled flow replaced a multi-minute agentic search sweep with one 4.5-second deterministic call at zero model tokens. Nothing in the loop is provider-specific — the dogfood happens to use a self-hosted SearXNG wrapper, but any MCP server exposing a search (or any other read-only) tool slots into servers.json5 the same way.

This is not "automatic workflow generation": a generated flow carries provenance for every inference, warns where the DSL cannot express the source, and requires review before serving — and always before writes. The precise claim: existing MCP workflow engines execute workflows; FlowMCP is designed to compile observed tool use into small, reviewable workflow tools, and then execute them deterministically. Intelligence at build time, determinism at runtime.

The registry: promotion and rot detection (v0.6)

A compiled flow is deterministic code, and deterministic code can silently rot. The registry is the maintenance layer: drop a registry.json5 beside your flows and the directory becomes governed — every flow must be listed with a state (candidate → reviewed → active → retired), only active flows are served, and an unlisted flow file is a loud startup error. Entries carry provenance (source trace, authoring model) and review records. No registry file → nothing changes.

With a registry present, every flow execution is logged to registry-log.jsonl — an open append-only contract that external systems write to as well: a consuming agent's editorial layer can append signal records ("this lens of the output was thin, I patched it"), and a shadow-replay harness can append shadow records (flow output vs the specialist path). npm start -- --flows <dir> --status computes per-flow health and prints advisory nominations, in cost order:

• Loud failure counting (free): 3+ consecutive failed runs → needs review.

• Consumer signals (free): the same lens patched in each of the last 3 gap-check signals → recompile candidate — this catches stale-but-well-formed output, the rot no structural check can see, using judgment the consumer was already paying for.

• Shadow replay (paid, scheduled): flowmcp shadow <flow> --agent '<cmd>' --judge '<cmd>' re-derives the task through a host-supplied agent, has a host-supplied judge compare, and records the verdict. FlowMCP never calls a model — the agent and judge are injected commands; without a judge nothing is recorded. Write flows are refused (shadowing one would write twice).

Nominations are advisory: --status never mutates the registry. Promotion and retirement stay human decisions — the registry's job is to make them informed and cheap. Full spec in FORMAT.md.

Trust model

Flow files are trusted programs — treat them like code, review them like code. The expression language can't execute code, but a flow can still send data to any URL it names; what bounds the blast radius is what the flow can see: only the env vars it declares in env: [...] (never all of process.env), only the 0–3 inputs it declares, and only downstream MCP tools that are read-only or explicitly allowlisted. servers.json5 is operator configuration, same trust level as the server's own command line. Don't load flow files you haven't read.

Design constraints (on purpose)

• Hand-rolled server protocol, ~150 lines: initialize, tools/list, tools/call, ping over newline-delimited JSON-RPC on stdio — small enough to audit in one sitting. The line we hold: we implement the MCP surface we govern; we use the reference client for downstream interoperability.

• Dependencies: zod, json5, and the official MCP SDK — used ONLY as the reference client transport for consuming remote (Streamable HTTP) downstream servers, pinned to its v1 line. FlowMCP's governed server runtime and workflow engine are hand-built and intentionally small; commodity protocol churn is delegated to the reference client.

• Small surfaces everywhere: few tools, ≤300-char descriptions, ≤3 params. Every token in tools/list is budget spent by every client on every turn.

• Writes are gated by construction. A flow containing a write step (a POST, or an mcp_call to an allowlisted tool) automatically gets a two-phase confirmation protocol — there is no opt-out flag. The first call runs the read steps, pauses before the first write, and returns a proposal plus a single-use confirmation token (5-minute expiry) bound to the frozen pre-write state; confirming executes exactly what was proposed, never a recomputation. A proposal template on the flow customizes the prompt. Write flows advertise readOnlyHint: false and a confirm parameter — all computed from the steps, never declared. With an elicitation-capable client (v0.5), approval is host-mediated instead: the server elicits {approve} through the host and the model never holds a token; missing required parameters are elicited the same way. With plain clients, the token protocol applies — a checkpoint, not a guaranteed human gate.

• stdout is the protocol channel; all logging goes to stderr.

Roadmap

Done and shipped: the six-condition benchmark (report, frozen at tag bench-2026-07-31), the trace→flow compiler and authoring loop (now first-class CLI: flowmcp author / compile / detect; the benchmark corpus stays in bench/), remote Streamable HTTP downstreams with operator attestation + schema drift pinning (v0.4), host-mediated write approval via elicitation (v0.5), the flow registry with promotion states, run logging, and staleness nominations (v0.6), the unified flowmcp CLI (v0.7, on npm), and the shadow-verification harness with host-injected agent and judge (v0.8).

Ahead:

• A broader benchmark task suite: more decline and partial-match shapes, tasks with no flow coverage, more trials per cell

• MCP conformance matrix (Inspector-based CI against current protocol revisions)

• Destination allowlists and HTTPS policy for http_request

• HTTP transport for the server itself

• Flow hot-reload

Development

npm test            # vitest: spawns the real server, speaks JSON-RPC, mocks only outbound HTTP
npm run typecheck   # strict TS, no emit
npm run build       # emits dist/ — the `flowmcp` bin entry points there

CI runs typecheck + tests on Node 20 and 22 for every push. Engineering log — what worked, what didn't, what the fix was — lives in DECISIONS.md. The flow file format is specified as a portable contract in FORMAT.md; benchmark method and results live in bench/.

MIT license.