MCP servers

walkerOS provides Model Context Protocol servers for AI assistant integration.

Server	What it covers	Sign-in
The hosted walkerOS MCP server, https://app.walkeros.io/api/mcp	Everything stored in the walkerOS app: projects, saved flows, deployments, previews, Observe, frames, release history, secrets, feedback	OAuth, in your browser
@walkeros/mcp	Local flow tools on your machine: validate, examples, load, simulate, bundle, push, package lookup, reference resources, prompts	None, no account
@walkeros/mcp-source-browser	HTML tagging: generate, parse, and validate data-elb attributes	None

Claude Code plugin

The recommended way to get started in Claude Code. One plugin installs the local @walkeros/mcp server, adds the hosted walkerOS MCP server, and installs 22 skills that teach Claude how to build sources, destinations, transformers, and flows.

Step 1: add the marketplace:

/plugin marketplace add elbwalker/walkerOS

Step 2: install the plugin:

/plugin install walkeros@elbwalker

That's it. Claude Code will reload with the MCP tools and skills active. The local tools work right away. The hosted server asks you to sign in once: run /mcp, pick it, and sign in (see Claude Code).

Quick start

For other MCP clients, add the servers to your configuration manually:

{
  "mcpServers": {
    "walkeros-flow": {
      "command": "npx",
      "args": ["@walkeros/mcp"]
    },
    "walkeros": {
      "type": "http",
      "url": "https://app.walkeros.io/api/mcp"
    },
    "walkeros-source-browser": {
      "command": "npx",
      "args": ["@walkeros/mcp-source-browser"]
    }
  }
}

The two local servers start on STDIO and register their tools automatically. The hosted entry is a remote server, for clients that take one in their configuration file. In Claude Code, add it with one command:

claude mcp add --transport http walkeros https://app.walkeros.io/api/mcp

In Claude Desktop and claude.ai, add it as a custom connector instead (see Connect Claude Desktop, claude.ai or Cursor).

Your first flow via AI

Everything in this loop runs locally, no account:

1. Install the plugin: /plugin install walkeros@elbwalker
2. Ask: "Create a web flow with a GA4 destination, validate it, and simulate a page view."
3. The assistant runs flow_load → flow_validate → flow_simulate and shows you the result.

Environment variables

@walkeros/mcp and @walkeros/mcp-source-browser need no environment variables, and the hosted server needs none either: it signs you in with OAuth. The local server's anonymous usage telemetry follows the CLI setting, see Telemetry.

---

@walkeros/mcp (local flow tools)

The local server runs on your own machine. It reads flow configs from inline JSON, files and URLs, and it bundles, simulates and pushes flows in its own process. It needs no account. package_search and package_get read npm and jsDelivr.

Installation

npm install @walkeros/mcp

Programmatic usage

@walkeros/mcp exports the server factory, so a local process can run the server over any MCP transport instead of the stdio binary:

import { createWalkerOSMcpServer, createLocalRuntime } from '@walkeros/mcp';

// An McpServer from the MCP TypeScript SDK: connect it to any transport.
const server = createWalkerOSMcpServer({
  runtime: createLocalRuntime(),
  version: '1.0.0',
});

The server reads, bundles and runs flows only through its runtime, which decides what the process may do. createLocalRuntime() keeps every capability, including local files, URLs and in-process bundling, simulation and push, and belongs only on the user's own machine; the stdio binary uses it.

To use the tools without an McpServer (for example with the Vercel AI SDK), call createToolHandlers(runtime). It returns the eight tool specs, each with its name, title, description, input schema, annotations and handler.

A host that registers the shared tools on its own server imports from @walkeros/mcp/specs: createLocalToolSpecs(runtime) returns the five tools both walkerOS servers offer (flow_validate, flow_examples, flow_load, package_search, package_get), and KNOWLEDGE_RESOURCES and PROMPTS are the reference resources and the prompts. Such a host passes a runtime that has load only and never registers bundle, simulate or push. It imports everything from @walkeros/mcp/specs (the specs, RuntimeRefusal, FlowRuntime, the envelope helpers), never from the main entry, which loads the CLI.

The stdio binary stays available via @walkeros/mcp/stdio and the walkeros-mcp bin entry.

Tools

Every tool answers with an object in structuredContent, and its text block carries the same object as JSON. A list sits under a named key, or under items when the tool has no name for it, and a bare value under value. Text that people write and the assistant should only read comes back wrapped in <user_data>...</user_data>. The rule is general: values people write are wrapped, while keys and identifiers (config keys, step names, settings names) stay literal, so a returned config round-trips unchanged.

flow_load

Load a flow configuration from inline JSON, a local file path or an http(s) URL, or create a new empty flow by specifying a platform.

Parameter	Type	Required	Description
source	string	No	Flow source: inline JSON, a file path such as ./flow.json, or an http(s) URL. Omit to create new.
platform	"web" | "server"	No	Platform for new flows. Required when source is omitted.

Returned configs are round-trip safe: structural values such as package names, platform, and IDs come back literally, so a loaded config can be edited and written back without altering anything you did not change.

flow_validate

Validate walkerOS events, flow configurations, mapping rules, or data contracts.

Parameter	Type	Required	Description
type	"event" | "flow" | "mapping" | "contract"	Yes	Validation type
input	string	Yes	Inline JSON, a file path, or an http(s) URL to validate
flow	string	No	Narrow every per-flow check to this flow; file-level checks still run
path	string	No	Check one entry (e.g. destinations.snowplow, stores.cache) against its package schema in every flow that has it, or only in flow
strict	boolean	No	Turns warnings and skipped checks into failures: valid is false, the verdict of walkeros validate --strict (exit 2). Contract example disagreements become errors
offline	boolean	No	Do not fetch package schemas; step settings are not checked, and details.scope.offline says so

With only type and input, a flow runs every check on every flow and step, including each step's settings against its package schema. It returns the same result as walkeros validate --json (see Validate command for the fields and codes): valid, errors[] and warnings[] with a stable code, and details.scope (what was checked), details.skipped (checks that could not run, with a reason and code) and details.deferred (values known only at runtime). A valid result with skips is valid only in the checked scope; the hint says how many checks were skipped. Branch on code, never on message. A step that imports a named export is checked against that export's settings schema, as in the CLI. A step whose package is a local path is checked from disk relative to the input file, as in the CLI.

flow_bundle

Bundle a walkerOS flow configuration into deployable JavaScript.

Parameter	Type	Required	Description
configPath	string	Yes	Flow config: a file path, an http(s) URL, or inline JSON
flow	string	No	Flow name for multi-flow configs
stats	boolean	No	Return bundle statistics (default: true)
output	string	No	Output file path

Bundle stats report the real total bundle size and the included package names (no per-package size estimate).

flow_simulate

Simulate events through a walkerOS flow without making real API calls. Returns summarized per-destination results. The result passes the same secret masking as the CLI: credential fields and the values of the secrets the flow references show as ***.

Parameter	Type	Required	Description
configPath	string	Yes	Flow config: a file path, an http(s) URL, or inline JSON
event	string | object	Yes	Event input (see shapes below). JSON string, file path, or URL also accepted.
step	string	Yes	Target step as "type.name" (e.g. "source.demo", "collector.default", "destination.gtag", "transformer.router")
flow	string	No	Flow name for multi-flow configs
platform	"web" | "server"	No	Override platform detection
verbose	boolean	No	Include full payload per destination (default: false)
ingest	object	No	Request context a step reads via ctx.ingest (transformer, collector and destination steps)
state	object	No	Collector state the step starts from: consent (booleans; every step, for a source the consent a consent-gated source waits for), user, globals, timing (collector steps)
command	"config" | "consent" | "user" | "run"	No	Destination steps only: run this collector command with event as its data instead of pushing it

There are four step types: source, collector, transformer, and destination. The event shape depends on the step type:

• Destinations / transformers: a walkerOS event, { name: "entity action", data: {...} }. The event's own consent (e.g. { marketing: true }) counts toward the destination's consent check, on top of state.consent. With command, event is the command's data (e.g. { marketing: true } for consent).
• Collector: the enrichment step. It takes a post-next partial event plus an optional state snapshot { consent?, user?, globals?, timing? }, applies the collector's createEvent, and returns the fully enriched event.
• Sources: { content, trigger? }, where content is the walkerOS event { name, data } and the optional trigger is { type?, options? }. There is no env field in the source-step event. A web source's page URL goes in trigger.options.url (default http://localhost).

Sources can be simulated as a step, including the @walkeros/source-demo demo source. Only the simulated source starts, and a destination simulation starts only its target destination. A source result lists the walker commands the source issues itself (a CMP's walker consent, the session source's user and session) as elb calls, also without verbose, and its summary counts them: Source captured 1 event and 2 commands. Calls of a source's mock client (for example the SQS source) appear only with verbose.

Consent. state.consent is the collector consent the step starts from. A destination with require: ["consent"] waits until consent is present, so pass state.consent to start it. A destination with consent: { marketing: true } receives an event only when that consent is granted in state.consent or in the event's own consent. When a destination sends nothing, its result carries skipped (reason: "pending" with the unmet require entries, or reason: "consent" with required and granted), and _hints.warnings explains it. With command, state.consent still applies first. See consent in simulate for the CLI equivalent.

Repeated simulations of the same inline configuration reuse a prebuilt bundle, so successive calls run faster; a file path or URL always rebuilds.

Transformer, collector and destination steps also accept an optional ingest field, a raw ingest without _meta. Supply it to test a request decoder standalone, for example a GA4 decoder that reads ctx.ingest.url: pass ingest: { url: "..." } alongside the event.

flow_push

Push a real event through a walkerOS flow to actual destinations. This makes real API calls. Best for server-side flows. Web destinations require browser globals not available in Node.js. The result passes the same secret masking as the CLI: credential fields and the values of the secrets the flow references show as ***.

Parameter	Type	Required	Description
configPath	string	Yes	Flow config: a file path, an http(s) URL, or inline JSON
event	object	Yes	Event object, e.g. { "name": "page view", "data": { "title": "Home" } }
flow	string	No	Flow name for multi-flow configs
platform	"web" | "server"	No	Override platform detection

flow_examples

List all step examples in a walkerOS flow configuration.

Parameter	Type	Required	Description
configPath	string	Yes	Flow config: inline JSON, a file path, or an http(s) URL
flow	string	No	Flow name for multi-flow configs
step	string	No	Filter to a specific step (e.g., "destination.gtag")
full	boolean	No	Return full in/out/mapping data (default: false, metadata only)
includeHidden	boolean	No	Include examples marked public: false (default: false)

When a step has no inline examples, flow_examples falls back to the examples shipped with that step's package, tagged by source so you can tell inline examples from package-provided ones.

package_search

Browse walkerOS packages or look up a specific one. Without package name: returns catalog filtered by type/platform. With package name: returns metadata.

Parameter	Type	Required	Description
package	string	No	Exact npm package name for lookup
type	"source" | "destination" | "transformer" | "store"	No	Filter by type (browse)
platform	"web" | "server"	No	Filter by platform (browse)
version	string	No	Package version (default: latest)

In browse mode the tool returns the complete catalog. If it has to fall back to a partial source or omit packages, the response includes a warnings array explaining what is incomplete rather than silently returning a partial list.

package_get

Fetch walkerOS package details from npm. By default returns schemas + hint texts + example summaries. Use section parameter for full content.

Parameter	Type	Required	Description
package	string	Yes	Exact npm package name
version	string	No	Package version (default: latest)
section	"hints" | "examples" | "all"	No	Section to expand with full content

A package with several exports (for example @walkeros/server-destination-gcp with destinationBigQuery and destinationPubSub) also returns exportSchemas: per export name, the same shape as schemas, with config merged from that export's settings. Configure a step that imports destinationPubSub from exportSchemas.destinationPubSub.config.

Tools for the walkerOS app

Projects, saved flows, deployments, previews, secrets, Observe, release history, frames and feedback are tools of the hosted walkerOS MCP server, not of this package. The hosted server describes them itself when a client connects; see Two servers.

Resources

URI	Description
walkeros://reference/flow-schema	Flow.Json structure and connection rules
walkeros://reference/event-model	Event naming, properties, auto-populated fields
walkeros://reference/mapping	Mapping syntax (data/map/loop/set/condition/consent/policy)
walkeros://reference/consent	Consent model (destination and field level)
walkeros://reference/variables	Variable patterns ($var/$env/$code/$store)
walkeros://reference/contract	Event schemas, wildcards, inheritance
walkeros://reference/examples	A complete, tested flow config with web, server and warehouse flows
walkeros://reference/packages	Full package catalog as { catalog, count, warnings? }; warnings says when the npm search failed, so a partial catalog is never read as an empty one
walkeros://schema/{packageName}	Per-package JSON schemas

Prompts

Prompt	Description
add-step	Add a source, destination, transformer, or store to a flow
setup-mapping	Configure event mapping for a step
manage-contract	Create/update event contracts (bidirectional with mappings)

Two servers

walkerOS has two flow MCP servers, and an assistant can use both at once.

Server	How it runs	What it works on	Sign-in
Local, @walkeros/mcp	npx @walkeros/mcp over stdio, or the Claude Code plugin, on your own machine	Files and URLs: validate, examples, load, simulate, bundle, push, package lookup, reference resources, prompts	None
Hosted walkerOS MCP server	https://app.walkeros.io/api/mcp over Streamable HTTP, inside the walkerOS app	What the walkerOS app stores: projects, saved flows, deployments, previews, Observe, frames, release history, secrets, feedback	OAuth, discovered from the endpoint itself

Both offer flow_validate, flow_examples, flow_load, package_search and package_get. The hosted one works on saved flows and inline JSON, the local one on files and URLs. The hosted server has no access to your files and never bundles, simulates or pushes a flow.

Running a saved flow locally. To simulate, bundle or push a flow saved in the walkerOS app, ask the hosted server's flow_manage for a config link (action: "config_url"). The link lasts about ten minutes. Pass it as the config input of the local flow_load (source) or of flow_simulate, flow_bundle or flow_push (configPath): the local server reads the config from the link, so the config itself never travels through the model. An expired link fails with its HTTP status (410), and a link to a flow saved again since it was made answers 409; ask for a fresh link in both cases.

Connect Claude Desktop, claude.ai or Cursor

The hosted server is one HTTPS endpoint: https://app.walkeros.io/api/mcp. It is the only value a client needs. No token, no header, no advanced field.

The endpoint runs an OAuth 2.1 authorization server, and a standard MCP client finds it on its own. You paste the URL, the client discovers who authorizes it and registers itself, a browser opens on a consent screen, you press Allow, and the client holds a token it refreshes without ever asking again.

Claude Desktop and claude.ai

1. Settings, then Connectors.
2. Add custom connector.
3. URL: https://app.walkeros.io/api/mcp. Leave every advanced setting alone.
4. The consent screen opens. Allow.
5. The walkerOS tools appear in the client.

Claude Code

claude mcp add --transport http walkeros https://app.walkeros.io/api/mcp

Then run /mcp inside Claude Code and choose to sign in. A browser opens on the consent screen, Allow, and the browser hands back to Claude Code on a local port. /mcp then lists the walkerOS tools. The Claude Code plugin adds this server for you.

Cursor and other MCP clients

Any client that speaks Streamable HTTP MCP takes the same URL, https://app.walkeros.io/api/mcp, in its MCP server settings. Everything else is discovered.

What the consent screen asks for

Permission	What it means
Read your projects and flows	List and read projects, flows, deployments, settings and observation data.
Change and deploy flows	Create, edit, deploy and delete flows, and manage project secrets and previews.
Stay connected	Keep working without signing in again, until you disconnect it.

Consent is per person, once, and it applies to every project that person belongs to. Which project a given action touches stays a choice made in the conversation, not at connect time.

If you are not signed in to walkerOS in that browser, the magic-link login runs first and hands back to the consent screen afterwards.

Disconnecting

Account, then Connected apps, lists every connected client with the permissions it was given and when it last called. Disconnect takes effect on that app's very next request, and it can be connected again at any time.

A credential for a machine

A script or a CI job has nobody to press Allow. Mint an automation token instead, under Account, then Automation tokens: pick read or read and write, pick a lifetime, and copy the wos_pat_... value once. Send it as Authorization: Bearer to the hosted server, or use it with walkeros api from a terminal or a CI job.

Availability

The hosted server is available to every walkerOS account. A connected client acts as you: it reads and changes every project you are a member of. A call that needs a feature the project does not include answers FEATURE_NOT_AVAILABLE and names the feature.

If something goes wrong

Symptom	Cause	Fix
The client says it cannot authenticate	The URL is wrong, or points at an environment that is down	Check it is exactly https://app.walkeros.io/api/mcp
The browser opens on the login page instead of the consent screen	Not signed in to walkerOS in that browser	Sign in; the consent screen follows on its own
The app suddenly asks to reconnect	It was disconnected under Account, Connected apps	Reconnect it, or leave it disconnected

Against stage, substitute https://stage.app.walkeros.io/api/mcp; against a local app, http://localhost:3000/api/mcp.

---

@walkeros/mcp-source-browser (HTML tagging tools)

Generate, parse, and validate walkerOS data-elb HTML attributes using real DOM parsing (JSDOM). No API token or CLI dependency required.

Installation

npm install @walkeros/mcp-source-browser

Tools (3)

generate_tagging

Generate walkerOS data-elb HTML attributes from structured input. Returns attribute key-value pairs and an example HTML snippet.

Parameter	Type	Required	Description
entity	string	No	Entity name (creates data-elb="entity")
data	object	No	Entity properties as key:value pairs
action	object	No	Trigger:action pairs for data-elbaction (nearest entity)
actions	object	No	Trigger:action pairs for data-elbactions (all entities)
context	object	No	Context properties for data-elbcontext
globals	object	No	Global properties for data-elbglobals
link	object	No	The one link for data-elblink, as {"id": "type"}, for example {"details": "parent"}. An element carries one link, so more than one entry is refused.
prefix	string	No	Custom prefix (default: data-elb)

At least one parameter must be provided.

parse_tagging

Parse HTML with data-elb attributes using real DOM parsing (JSDOM). Extracts all walkerOS events and globals.

Parameter	Type	Required	Description
html	string	Yes	HTML snippet with data-elb attributes
prefix	string	No	Custom prefix (default: data-elb)

validate_tagging

Validate HTML data-elb tagging for common mistakes. Checks for orphan actions, missing entities, unknown triggers, orphan properties, and entities without actions.

Parameter	Type	Required	Description
html	string	Yes	HTML snippet to validate
prefix	string	No	Custom prefix (default: data-elb)

Resources

URI	Description
walkeros://docs/tagging/html-attributes	Complete guide to data-elb HTML attribute tagging
walkeros://docs/tagging/tagger	createTagger() fluent API reference

---

Example workflows

Create and validate a flow

Ask your AI assistant:

"Create a new web flow, add a GA4 destination, then validate it."

The assistant uses flow_load to create a skeleton, the add-step prompt to add GA4, and flow_validate to check the result.

Simulate events

"Simulate a page view event through my flow at ./flow.json."

The assistant calls flow_simulate and returns per-destination results showing which destinations received the event.

Simulate a saved flow

Needs both servers.

"Simulate a page view through my saved checkout flow."

The assistant asks the hosted server for a config link to the saved flow and passes it to the local flow_simulate, so the config never passes through the conversation.

Deploy a flow

Needs the hosted server and a walkerOS account. The local loop (create, validate, simulate) needs neither.

"Deploy my checkout flow and wait for it to finish."

The assistant finds the flow among your saved flows, deploys it through the hosted server, and reports when the deployment is live or has failed.

Preview a flow on a live site

Needs the hosted server and a walkerOS account.

"Create a preview of my demo settings and give me the link to open on https://example.com."

The assistant creates the preview through the hosted server and returns an activation link that switches your browser on that site to the preview. When the preview is deleted later, the production walker self-heals on visitors' next page load.

Set up event mapping

"Help me set up mapping for the gtag destination in my flow."

The assistant uses the setup-mapping prompt, reads the mapping reference resource, fetches package examples, and generates mapping rules.

Generate HTML tagging

"Generate data-elb attributes for a promotion entity with name 'Summer Sale' and a click action."

The assistant calls generate_tagging with entity: "promotion", data: { name: "Summer Sale" }, and action: { click: "click" }, returning ready-to-use HTML attributes.

Discover a package

"What configuration does the Snowplow destination need?"

The assistant calls package_search for @walkeros/web-destination-snowplow, then package_get to fetch schemas, hints, and examples.

Next steps

• CLI: Learn about the underlying CLI commands
• Flow configuration: Understand flow structure
• HTML attributes: Learn about data-elb tagging
• MCP specification: Learn about the Model Context Protocol