MCP clients

wxctl ships a local Model Context Protocol server, wxctl mcp serve, that exposes its tools to any MCP-capable client over stdio. An agent can discover resource kinds, validate and plan configs, and (with confirmation) apply, test, and destroy them. For config authoring with no local install, point a client at the hosted Worker instead.

Tool surface

Group	Tools	Availability
Discovery	`wxctl_list_resource_kinds`, `wxctl_explain_kind`	Always (read-only)
Author & preview	`wxctl_validate`, `wxctl_plan`	Always (read-only)
Run inspection	`runs_list`, `run_get`, `run_events_query`, `run_diagnose`	Always (read-only)
Generate	`compose_start`, `compose_paths`, `compose_prompt`	Always (read-only)
Mutate	`wxctl_apply`, `wxctl_destroy`, `wxctl_test`, `compose_scaffold`	Apply and destroy require `confirm: true`; all four dropped under `--read-only`

wxctl_validate returns warnings (non-blocking advisories) alongside valid, errors, and fix_prompt. wxctl_apply and wxctl_destroy refuse to run without confirm: true, and wxctl_apply additionally expects a preceding error-free wxctl_plan. Start the server with --read-only to register only the read-only tools, so mutation is impossible by construction; recommended for unattended agents.

wxctl mcp serve              # full tool set (apply/destroy/test gated by confirm:true)
wxctl mcp serve --read-only  # discovery, validation, plan, and inspection only

IBM Bob

Add the server to the project’s .bob/mcp.json, or to ~/.bob/mcp_settings.json to make it available in every workspace:

{
  "mcpServers": {
    "wxctl": {
      "command": "wxctl",
      "args": ["mcp", "serve"]
    }
  }
}

List tool names under alwaysAllow to skip the per-call approval prompt, for example "alwaysAllow": ["wxctl_validate", "wxctl_plan"].

Replace "wxctl" with the absolute path to the binary (for example /path/to/wxctl) if it is not on the client’s PATH. If you installed wxctl with npm, you can instead set "command": "npx" with "args": ["wxctl", "mcp", "serve"] to avoid a PATH lookup. Append a profile and read-only flag through args, for example "args": ["mcp", "serve", "--read-only", "-p", "staging"].

From a scenario to a tested deployment

One plain-language scenario in, a tested live deployment out. With the server wired in, the agent starts with compose_start, which returns the ordered recipe and its guardrails (a bounded validate-and-fix loop, the error-free-plan-before-apply gate). The agent’s own model then does the generation passes: the config, the kind: test suite, and the tool implementations. This walkthrough uses the scenario behind the calculator-weather-agents example. For a step-by-step tutorial of this exact flow, see the Generative quickstart.

Configure a profile with watsonx Orchestrate credentials.
Start from a directory containing only use-case.txt with the scenario:

A calculator agent that does arithmetic with a Python tool and answers IBM
history questions from a knowledge base, plus a weather agent that reports
city weather and delegates any math to the calculator agent

Give the agent one instruction:

Read use-case.txt and take that scenario end to end with the wxctl MCP tools:
start with compose_start and follow its recipe to generate, validate, and
deploy the config, run the tests, then destroy everything. Report each stage.

The agent works through the recipe:

Stage	Tools	What happens
Recipe	`compose_start`	Returns the ordered steps, the fix-loop policy, and the plan-before-apply gate
Generate	`compose_paths`, `compose_prompt`	The agent’s model writes `config.yaml`: a knowledge base, two Python tools, two collaborating agents, and a generated `kind: test` suite
Check	`wxctl_validate`	Schema and reference checks; an invalid config returns a fix prompt (at most 3 iterations)
Scaffold	`compose_scaffold`	Materializes the tool source stubs on disk; the agent fills in the implementations and the knowledge-base document
Preview	`wxctl_plan`	The dependency-ordered create plan, which must be error-free
Deploy	`wxctl_apply` (`confirm: true`)	Creates the resources
Prove	`wxctl_test`	Runs the generated tests against the live deployment
Reset	`wxctl_destroy` (`confirm: true`)	Tears everything back down

wxctl_apply refuses to run until a preceding wxctl_plan succeeds, so the agent cannot skip the preview.

Headless with `bob -p`

Bob Shell runs the whole flow unattended in a non-interactive session:

mkdir demo && cd demo
echo "A calculator agent that does arithmetic with a Python tool and answers \
IBM history questions from a knowledge base, plus a weather agent that reports \
city weather and delegates any math to the calculator agent" > use-case.txt

bob -p "Read use-case.txt and take that scenario end to end with the wxctl MCP \
tools: start with compose_start and follow its recipe to generate, validate, and \
deploy the config, run the tests, then destroy everything. Report each stage." \
  --yolo

--yolo approves the tool calls and file writes that a non-interactive session would otherwise refuse (the generated config.yaml and tool sources land in the current directory). The confirm: true gate on apply and destroy still applies inside the server, and the plan-before-apply rule still holds. To let an unattended agent explore with no possibility of mutation, register the server with --read-only instead. This is that run, fast-forwarded. Bob generates the config and the implementations, deploys, proves it with the tests it wrote, and tears it all down:

Remote Worker (config authoring only)

The hosted Worker exposes the config-authoring tools (discovery, schema, validation, examples) with no credentials and nothing to install. It cannot reach any account or live API, so it stops at a validated config.yaml. Hand off to the local server for plan/apply/test. Native HTTP clients point at the endpoint directly:

{
  "mcpServers": {
    "wxctl-config": {
      "type": "http",
      "url": "https://wxctl-config.randyphoa.workers.dev/mcp"
    }
  }
}

Stdio-only clients bridge with mcp-remote:

{
  "mcpServers": {
    "wxctl-config": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://wxctl-config.randyphoa.workers.dev/mcp"]
    }
  }
}

Tool surface

IBM Bob

From a scenario to a tested deployment

Headless with `bob -p`

Remote Worker (config authoring only)

Next steps

Generate a config from a scenario

Resource kinds

​Tool surface

​IBM Bob

​From a scenario to a tested deployment

​Headless with bob -p

​Remote Worker (config authoring only)

​Next steps

Generate a config from a scenario

Resource kinds

Tool surface

IBM Bob

From a scenario to a tested deployment

Headless with `bob -p`

Remote Worker (config authoring only)

Next steps