@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:

{
  "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:

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

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

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:

1. flow_load creates an empty flow for a platform, or loads an existing one from a file, URL, or inline JSON.
2. 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.
3. package_get returns that package's configuration schema, hints, and worked examples, so the config is written against the real shape.
4. flow_validate checks the result. Fix and re-validate until it passes.
5. 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, app reachability, and the API contract verdict

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 and field level
walkeros://reference/variables	Variable patterns: $var, $env, $secret, $code, $store
walkeros://reference/contract	Event schemas, wildcards, and inheritance
walkeros://reference/openapi	The live OpenAPI 3.1 document of the app this server talks to
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	Project (proj_...) for calls without projectId, ahead of set_default
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:

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.

A ToolClient served inside a host that authenticates every request itself returns 'host' from credentialSource(). The auth tool then reports the connection as logged in, answers login with "no login needed" and refuses logout, which never reaches the client: the connection ends in the host.

A ToolClient may implement checkContract() and openapiDocument(). The diagnostics tool reports the first as its contract verdict, unknown when it is absent; the walkeros://reference/openapi resource serves the second. HttpToolClient implements both against the app it talks to. The tool roster ships as @walkeros/mcp/surface.json.

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