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://…

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

kind	fields	what it does
http_request	method (GET/POST), url, headers?, body?, timeoutMs? (default 15000)	Fetch a URL; JSON responses are parsed. One automatic retry on network error — GET only: a timed-out POST may have landed, so it is never retried.
transform	expr	Reshape prior results with a sandboxed expression — paths, object/array literals, comparisons. No code execution.
template	template	Mustache-style string build: {{steps.x.y[0]}}. Arrays join line-per-item; missing terminal values render as ''.
map	over, as? (default item), step	Run one leaf step per array element, sequentially, max 10 items — slice with steps.ids[0:5].
branch	if, then, else?	Evaluate a condition, run one of two step lists. No nested branches.
mcp_call	server, tool, args?, timeoutMs? (default 30000), maxResultChars? (default 8000)	Call one tool on a downstream MCP server from servers.json5. See Composition below.

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