io.walkeros/flow (MCP) Server

Model Context Protocol (MCP) server for walkerOS flow development. It provides AI tools to discover packages, build a flow configuration, validate it, simulate events through the flow, bundle it, and deploy it. The server is described as “@walkeros/mcp,” with documentation, an NPM link, and source code referenced by the package readme excerpt.

🛠️ Key Features

Discover packages
Build flow configuration
Validate flow configuration
Simulate events through the flow
Bundle flows
Deploy bundled flows

🚀 Use Cases

walkerOS event pipeline development
Verifying and testing event behavior via simulation
Preparing deployable bundles for flow configurations

⚡ Developer Benefits

Tooling aligned to the flow lifecycle (discover → build → validate → simulate → bundle → deploy)

⚠️ Limitations

Only the flow development workflow is described; no additional MCP capabilities or runtime details are provided.

@walkeros/mcp

Model Context Protocol server for walkerOS flow development. Gives an AI assistant the tools to discover packages, build a flow configuration, validate it, simulate events through it, bundle it, and deploy it.

Documentation • NPM Package • Source Code

Installation

The server runs over stdio and is started by your MCP client. Add it to the client's configuration:

json

{
  "mcpServers": {
    "walkeros-flow": {
      "command": "npx",
      "args": ["@walkeros/mcp"]
    }
  }
}

Client	File
Claude Code	`.mcp.json` in the project root
Cursor	`.cursor/mcp.json` in the project root
Claude Desktop	`claude_desktop_config.json`
VS Code	`.vscode/mcp.json`, with `servers` instead of `mcpServers`

In Claude Code you can also install the walkerOS plugin, which registers this server, the tagging server, and the walkerOS skills in one step:

code

/plugin marketplace add elbwalker/walkerOS
/plugin install walkeros@elbwalker

To install the binary directly instead of running it through npx:

bash

npm install @walkeros/mcp

No account required

The server starts, registers all tools, and runs the whole local loop without any credentials. auth reports { "authenticated": false } and the local tools work regardless. Only the walkerOS cloud tools need a credential.

Two ways to get one:

auth with action: "login" runs the RFC 8628 device authorization grant. It answers with a URL, you approve it in a browser you are already signed in to, and a second call with the same deviceCode resumes polling until the approval lands. The session that results refreshes itself, and it appears in the app under Account, Connected apps, where disconnecting it takes effect on the next call. auth with action: "logout" revokes it.
WALKEROS_TOKEN carries an automation token (wos_pat_...) minted in the app under Account, then Automation tokens. It is used as-is and never refreshed, which is what a CI job or a headless server wants.

There is no endpoint that mints a token from another token, and nothing issues sk-walkeros- or mcp-walkeros- values any more; rows carrying them keep verifying until they expire.

Quick start

Five tools cover building a flow from nothing to a tested configuration, and all five run locally:

flow_load creates an empty flow for a platform, or loads an existing one from a file, URL, or inline JSON.
package_search finds the exact package names for the sources, destinations, transformers, and stores the flow needs. Never guess a package name, search for it.
package_get returns that package's configuration schema, hints, and worked examples, so the config is written against the real shape.
flow_validate checks the result. Fix and re-validate until it passes.
flow_simulate pushes an event through the flow with vendor calls mocked and shows what each step produced.

Tools

The server registers 19 tools.

Local, no account

Tool	Description
`flow_load`	Load a flow from a file path, URL, inline JSON, or flow ID, or create an empty one
`flow_validate`	Validate an event, flow config, mapping rule, or data contract
`flow_simulate`	Run an event through a flow with mocked vendor calls and inspect each step
`flow_bundle`	Compile a flow into a tree-shaken, deployable JavaScript bundle
`flow_push`	Push a real event through a flow to real destinations, making real API calls
`flow_examples`	List the step examples in a flow, the fixtures simulation can replay
`package_search`	Find packages by name, type, or platform. The entry point for package discovery
`package_get`	Read one package's schemas, configuration hints, and examples by exact name
`diagnostics`	Report MCP and CLI versions, app URL, backend, and whether the app is reachable

walkerOS cloud

Tool	Description
`auth`	Check login status, log in through the device code flow, or log out
`project_manage`	List, create, update, or delete projects, and set the default one
`flow_manage`	List, create, update, delete, or duplicate saved flows, and manage their previews
`deploy_manage`	Deploy a flow and list, inspect, or delete its deployments
`secret_manage`	Manage a flow's `$secret.<NAME>` values. Write-mostly, values are never returned
`observe_session`	Start, inspect, or stop an Observe session, a time-boxed window on one running flow
`observe_journeys`	Read the assembled journeys for an observed flow, each event traced across web and server
`hub_manage`	Read a flow's release history and the reasoning behind it, and add to the discussion
`frame_manage`	Read the frames of a measurement plan, the named rectangles and the marks inside them
`feedback`	Send feedback about walkerOS

Resources

URI	Content
`walkeros://reference/flow-schema`	Flow configuration structure and connection rules
`walkeros://reference/event-model`	Event naming, properties, and auto-populated fields
`walkeros://reference/mapping`	Mapping syntax: data, map, loop, set, condition, policy
`walkeros://reference/consent`	The consent model at destination, rule, and field level
`walkeros://reference/variables`	Variable patterns: `$var`, `$env`, `$secret`, `$code`, `$store`
`walkeros://reference/contract`	Event schemas, wildcards, and inheritance
`walkeros://reference/openapi`	OpenAPI 3.1 specification for the walkerOS API
`walkeros://reference/packages`	The full package catalog
`walkeros://schema/{packageName}`	JSON schema for one package

Read these before writing a configuration by hand.

Prompts

Prompt	Purpose
`add-step`	Add a source, destination, transformer, or store to a flow
`setup-mapping`	Configure event mapping for a step
`manage-contract`	Create or update event contracts, in both directions with mappings

Environment variables

Variable	Required	Default	Purpose
`WALKEROS_TOKEN`	No	none	Automation token (`wos_pat_...`), an alternative to the `auth` tool login
`WALKEROS_PROJECT_ID`	No	none	Active project ID (`proj_...`)
`WALKEROS_APP_URL`	No	`https://app.walkeros.io`	Base URL override

Programmatic usage

The package exports a transport-agnostic server factory, so a host application can mount the protocol over HTTP instead of running the stdio binary:

typescript

import {
  createWalkerOSMcpServer,
  createHostedRuntime,
  HttpToolClient,
  createStreamableHttpHandler,
} from '@walkeros/mcp';

const client = new HttpToolClient();
const server = createWalkerOSMcpServer({
  client,
  version: '1.0.0',
  runtime: createHostedRuntime(client),
});

export const POST = createStreamableHttpHandler(server, {
  sessionIdGenerator: () => crypto.randomUUID(),
});

The server reads, bundles and runs flows only through a runtime, which decides what the process it lives in may do. createHostedRuntime(client) is the default when runtime is omitted and the right choice for anything reached over the network: it loads inline JSON and saved flow ids, refuses local file paths and URLs, and never bundles, simulates or pushes in the host process. createLocalRuntime() keeps every capability, including local files, URLs and in-process execution, and belongs only on the user's own machine; the stdio binary uses it.

To use the tool registry without the MCP protocol, for example with the Vercel AI SDK, call createToolHandlers(client, version, runtime) or import TOOL_DEFINITIONS and supply your own ToolClient. The stdio binary stays available as @walkeros/mcp/stdio and the walkeros-mcp bin entry.

Documentation

Full parameter tables, workflows, and examples live in the docs: https://www.walkeros.io/docs/apps/mcp

Contribute

Feel free to contribute by submitting an issue, starting a discussion, or getting in contact.

License

MIT

walkerOS Flow