Skip to main content
Ask your AI

MCP servers

walkerOS provides Model Context Protocol servers for AI assistant integration.

ServerWhat it coversSign-in
The hosted walkerOS MCP server, https://app.walkeros.io/api/mcpEverything stored in the walkerOS app: projects, saved flows, deployments, previews, Observe, frames, release history, secrets, feedbackOAuth, in your browser
@walkeros/mcpLocal flow tools on your machine: validate, examples, load, simulate, bundle, push, package lookup, reference resources, promptsNone, no account
@walkeros/mcp-source-browserHTML tagging: generate, parse, and validate data-elb attributesNone

Claude Code plugin​

The plugin is the recommended way to get started in Claude Code. It 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.

Add the marketplace:

/plugin marketplace add elbwalker/walkerOS

Then install the plugin:

/plugin install walkeros@elbwalker

Claude Code reloads 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 and needs 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). A running server reads that setting once, when its client connects: after walkeros telemetry disable, it keeps sending until you restart it.


@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, output schema (where the tool has one), 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 is available as @walkeros/mcp/stdio and as 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, package names, IDs) and the tool's own messages stay literal.

The advertised output schemas leave out _hints (except flow_validate's) and the { error, hint } error shape, so a client that validates structured output (the MCP TypeScript SDK Client after listTools) rejects every flow_load, flow_examples, flow_bundle and flow_simulate result, and every error result of a tool with an output schema, with MCP error -32602: Structured content does not match the tool's output schema. The hosted server registers the same schemas for its flow_validate, flow_load and flow_examples, error results included; Claude Code does not validate structured output, so these results reach it 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.

ParameterTypeRequiredDescription
sourcestringNoFlow source: inline JSON, a file path such as ./flow.json, or an http(s) URL. Omit to create new.
platform"web" | "server"NoPlatform for new flows. Required when source is omitted.

In a returned config, package names, platform, versions and IDs come back literally. Every other string value comes back wrapped, for example "title": "<user_data>Home</user_data>". Remove the wrapper from each value before writing the config back, or it becomes part of the value.

flow_validate​

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

ParameterTypeRequiredDescription
type"event" | "flow" | "mapping" | "contract"YesValidation type
inputstringYesInline JSON, a file path, or an http(s) URL to validate
flowstringNoNarrow every per-flow check to this flow; file-level checks still run
pathstringNoCheck one entry (e.g. destinations.snowplow, stores.cache) against its package schema in every flow that has it, or only in flow
strictbooleanNoTurns warnings and skipped checks into failures: valid is false, the verdict of walkeros validate --strict (exit 2). Contract example disagreements become errors
offlinebooleanNoDo 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.

ParameterTypeRequiredDescription
configPathstringYesFlow config: a file path or an http(s) URL. Inline JSON is not accepted: it is read as a file name and fails with Configuration file not found
flowstringNoFlow name for multi-flow configs
statsbooleanNoReturn bundle statistics (default: true). With false the bundle is still written, but the result reads success: false and Bundle produced no output
outputstringNoOutput 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 ***.

ParameterTypeRequiredDescription
configPathstringYesFlow config: a file path, an http(s) URL, or inline JSON
eventstring | objectYesEvent input (see shapes below), as an object or a JSON string. A file path or URL is not read: it fails with Event string must be valid JSON
stepstringYesTarget step as "type.name" (e.g. "source.demo", "collector.default", "destination.gtag", "transformer.router")
flowstringNoFlow name for multi-flow configs
platform"web" | "server"NoOverride platform detection
verbosebooleanNoInclude full payload per destination (default: false)
ingestobjectNoRequest context a step reads via ctx.ingest (transformer, collector and destination steps)
stateobjectNoCollector 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"NoDestination 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, runs collector.next, and returns every event the destinations would receive (none when the chain stops the 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.

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. It is best suited to server-side flows. Web destinations require browser globals that Node.js does not provide. The result passes the same secret masking as the CLI: credential fields and the values of the secrets the flow references show as ***.

ParameterTypeRequiredDescription
configPathstringYesFlow config: a file path, an http(s) URL, or inline JSON
eventobjectYesEvent object, e.g. { "name": "page view", "data": { "title": "Home" } }
flowstringNoFlow name for multi-flow configs
platform"web" | "server"NoOverride platform detection

flow_examples​

List all step examples in a walkerOS flow configuration.

ParameterTypeRequiredDescription
configPathstringYesFlow config: inline JSON, a file path, or an http(s) URL
flowstringNoFlow name for multi-flow configs
stepstringNoFilter to a specific step (e.g., "destination.gtag")
fullbooleanNoReturn full in/out/mapping data (default: false, metadata only)
includeHiddenbooleanNoInclude 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 examples are read at the version or local path the flow pins, and each one carries the version it was read from. A step whose package cannot be read is listed in the warnings: a version that does not exist, a version pinned through a $var reference (it is not resolved, although flow_bundle installs the resolved version), a local path without a walkerOS.json, or a local path in a config that is not a file (inline JSON, a URL, and every config on the hosted server).

Browse walkerOS packages or look up a specific one. Without a package name it returns the catalog, filtered by type and platform; with a package name it returns that package's metadata.

ParameterTypeRequiredDescription
packagestringNoExact npm package name for lookup
type"source" | "destination" | "transformer" | "store"NoFilter by type (browse)
platform"web" | "server"NoFilter by platform (browse)
versionstringNoPackage version (default: latest)

In browse mode the tool returns the published step packages that match the filters and whose walkerOS metadata it could read from jsDelivr. When the npm search fails, the catalog comes back empty with a warning that says so. A second warning counts the npm packages whose walkerOS metadata could not be read. That count includes every package that is not a step, such as @walkeros/core and @walkeros/cli, so this warning appears on every browse and does not by itself mean a step package is missing.

package_get​

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

ParameterTypeRequiredDescription
packagestringYesExact npm package name
versionstringNoPackage version (default: latest)
section"hints" | "examples" | "all"NoSection 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​

URIDescription
walkeros://reference/flow-schemaFlow.Json structure and connection rules
walkeros://reference/event-modelEvent naming, properties, auto-populated fields
walkeros://reference/mappingMapping syntax (data/map/loop/set/condition/consent/policy)
walkeros://reference/consentConsent model (destination and field level)
walkeros://reference/variablesVariable patterns ($var/$env/$secret/$contract/$code/$store)
walkeros://reference/contractEvent schemas, wildcards, inheritance
walkeros://reference/examplesA complete, tested flow config with web, server and warehouse flows
walkeros://reference/packagesThe package catalog as { catalog, count, warnings? }, read the same way as package_search browses: warnings says when the npm search failed (the catalog is then empty) and counts the npm packages without readable walkerOS metadata, which today includes every package that is not a step, so it is present on every read
walkeros://schema/{packageName}Per-package JSON schemas

Prompts​

PromptDescription
add-stepAdd a source, destination, transformer, or store to a flow
setup-mappingConfigure event mapping for a step
manage-contractCreate/update event contracts (bidirectional with mappings)

Two servers​

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

ServerHow it runsWhat it works onSign-in
Local, @walkeros/mcpnpx @walkeros/mcp over stdio, or the Claude Code plugin, on your own machineFiles and URLs: validate, examples, load, simulate, bundle, push, package lookup, reference resources, promptsNone
Hosted walkerOS MCP serverhttps://app.walkeros.io/api/mcp over Streamable HTTP, inside the walkerOS appWhat the walkerOS app stores: projects, saved flows, deployments, previews, Observe, frames, release history, secrets, feedbackOAuth, 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 whose config changed 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, header or 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 and the client discovers who authorizes it. It registers itself or presents its published client identity, a browser opens on a consent screen, you press Allow, and the client holds a token it refreshes on its own.

Claude Desktop and claude.ai​

  1. Customize, then Connectors.
  2. Press + Add, then Add custom connector.
  3. Enter a name, for example walkerOS, and the URL https://app.walkeros.io/api/mcp, then Continue.
  4. Keep the detected authentication settings and Continue. Under Authentication pick a sign-in option other than No sign in, keep the recommended OAuth client, then Add.
  5. When you sign in, the walkerOS consent screen opens: press Allow.
  6. In a conversation, turn the connector on under +, then Connectors.

On Team and Enterprise plans an owner adds the connector first (Organization settings, then Connectors), and each member then presses Connect on it (Customize, then Connectors).

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; press 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.

PermissionWhat it means
Read your projects and flowsList and read projects, flows, deployments, settings and observation data.
Change and deploy flowsCreate, edit, deploy and delete flows, and manage project secrets and previews.
Stay connectedKeep working without signing in again, until you disconnect it or it goes unused for 90 days.

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 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​

SymptomCauseFix
The client says it cannot authenticateThe URL is wrong, or points at an environment that is downCheck it is exactly https://app.walkeros.io/api/mcp
The browser opens on the login page instead of the consent screenNot signed in to walkerOS in that browserSign in; the consent screen follows on its own
The app suddenly asks to reconnectIt was disconnected under Account, Connected appsReconnect 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). It needs no API token and does not depend on the CLI.

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.

ParameterTypeRequiredDescription
entitystringNoEntity name (creates data-elb="entity")
dataobjectNoEntity properties as key:value pairs
actionobjectNoTrigger:action pairs for data-elbaction (nearest entity)
actionsobjectNoTrigger:action pairs for data-elbactions (all entities)
contextobjectNoContext properties for data-elbcontext
globalsobjectNoGlobal properties for data-elbglobals
scopedobjectNoPath-scoped generic properties for data-elb_, which only triggers nested below the element receive
linkobjectNoThe one link for data-elblink, as {"id": "type"}, for example {"details": "parent"}. An element carries one link, so more than one entry is refused.
prefixstringNoCustom prefix (default: data-elb)

At least one parameter other than prefix must be provided.

parse_tagging​

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

ParameterTypeRequiredDescription
htmlstringYesHTML snippet with data-elb attributes
prefixstringNoCustom prefix (default: data-elb)

validate_tagging​

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

ParameterTypeRequiredDescription
htmlstringYesHTML snippet to validate
prefixstringNoCustom prefix (default: data-elb)

Resources​

URIDescription
walkeros://docs/tagging/html-attributesComplete guide to data-elb HTML attribute tagging
walkeros://docs/tagging/taggercreateTagger() 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​

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)