MCP tools reference¶

Reference guide for AI agents and MCP clients working with muster's tools. This document covers the meta-tools interface and the built-in tools that muster provides for managing platform resources.

Meta-Tools (Primary Interface)¶

All tool access goes through these meta-tools. MCP clients see only these 13 meta-tools when they connect to muster. All other tools are accessed via call_tool.

Tool Discovery¶

Meta-Tool	Description	Arguments
`list_tools`	List one bounded page of the session's tools (summarised; 50 per page by default)	`{"limit": 50, "offset": 0}`
`describe_tool`	Get detailed schema for a specific tool, and the `call_tool` call that invokes it	`{"name": "tool_name"}`
`filter_tools`	Discover tools cheaply (ranked, faceted, paginated)	`{"pattern": "...", "query": "...", "labels": {...}, "limit": 5}`
`list_core_tools`	List only muster core tools	`{}`

`list_tools` — the paged catalogue¶

list_tools answers one page of the caller's catalogue, never the whole of it: an installation of realistic size exposes hundreds of tools, and the unpaged listing of a 450-tool toolset measured 400 KB — about 135k tokens that then ride in the model's context for every following call. Each entry is the discovery-tier projection (name, one-line summary, server, kind, annotations); the full description and the input schema of a tool stay behind describe_tool.

Argument	Type	Default	Purpose
`limit`	number	`50`	Max tools in this page (at least 1).
`offset`	number	`0`	Tools to skip before this page.

The response carries total (tools in the caller's catalogue — the session's tools narrowed by the request's toolset), truncated (more tools exist beyond this page: fetch them with offset + limit), filtered_count (entries in this page), filters (the limit and offset applied), toolset (the request's X-muster-Toolset selectors when it declared one) and servers_requiring_auth (the servers a core_auth_login would unlock; neither paged nor narrowed by a toolset). A client that wants every tool — the muster CLI and REPL listings do — pages until truncated is false, or asks for a large limit.

Use list_tools for a bounded look at what is there; use filter_tools to find a tool and describe_tool to learn how to call it.

{
  "filters": {"case_sensitive": false, "include_schema": false, "limit": 50, "offset": 0},
  "total_tools": 450,
  "filtered_count": 50,
  "total": 450,
  "truncated": true,
  "tools": [
    {"name": "x_kubernetes_list_pods", "summary": "List pods in a namespace.", "server": "kubernetes", "kind": "tool", "annotations": {"readOnlyHint": true}}
  ],
  "servers_requiring_auth": [{"name": "github", "status": "auth_required", "auth_tool": "core_auth_login"}]
}

`describe_tool` — the authoritative detail, and how to call it¶

describe_tool returns one tool's full description and inputSchema together with its server, kind and annotations, and an invocation line naming the call that runs it. Every tool it can describe lives inside muster, where an MCP client sees only the meta-tools: issuing an aggregated tool's name as a tool call fails. Such a tool is reached through call_tool, and only through call_tool.

{
  "name": "x_kubernetes_list_pods",
  "description": "List pods in a namespace.",
  "server": "kubernetes",
  "kind": "tool",
  "annotations": {"readOnlyHint": true},
  "inputSchema": {"type": "object", "properties": {"namespace": {"type": "string"}}},
  "invocation": "Call it through the call_tool meta-tool: call_tool with {\"name\": \"x_kubernetes_list_pods\", \"arguments\": {...}}, arguments per inputSchema. Tools inside muster are not callable by name directly — only the meta-tools are."
}

`filter_tools` — the discovery tier¶

filter_tools is a cheap discovery tier, distinct from execution. Against a large fleet (hundreds of workflows) it returns a bounded, summarised, optionally ranked page rather than the full catalogue, so finding a tool costs a few hundred tokens instead of a full-catalogue dump.

Argument	Type	Default	Purpose
`pattern`	string	—	Glob match on the tool name (e.g. `x_kubernetes_*`).
`description_filter`	string	—	Case-insensitive substring match on the full description.
`query`	string	—	Natural-language query. When set, matches are relevance-ranked (field-weighted lexical BM25F over name + summary — name matches weigh higher than description matches, and ubiquitous verbs like `list`/`get` are down-weighted so the discriminating noun drives ranking), returned best-first with a `score`; non-matching tools are dropped.
`labels`	object	—	Label facets as key=value pairs. A tool must carry every given label to match. Only workflow tools carry labels today — they inherit the `Workflow` CRD's `metadata.labels`; core (`core_`) and external (`x_`) tools have none, so a `labels` facet currently scopes discovery to labelled workflows.
`case_sensitive`	bool	`false`	Case-sensitive name matching.
`include_schema`	bool	`false`	Return full descriptions and input schemas instead of one-line summaries.
`limit`	number	`5`	Max tools per page.
`offset`	number	`0`	Tools to skip before this page.
`toolset`	string[]	—	Inline toolset selectors (`preset:<name>`, `server:<name>`, `workflow:<name>`, `tool:<name>`, at most 32) to resolve against the caller's catalogue. The response adds `toolset` (echo of the argument; without the argument, of the request's `X-muster-Toolset`, so a scoped caller can learn what bounds it), `toolset_unmatched` (selectors that selected nothing for the caller) and `presets` (with the argument or `include_presets`). With `X-muster-Toolset` also on the request, the argument resolves within the header's toolset and never widens it. See Toolsets.
`include_presets`	bool	`false`	Add the known toolset presets (`name`, `description`, `built_in`) to the response.

The response carries total (matches across the caller's catalogue), truncated (more matches exist beyond this page), and per-tool a one-line summary (plus score when ranked and labels when present), the owning server (omitted for workflows and core tools), the kind (tool | workflow | core) and the tool's annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint as the server declared them; for a workflow the derived readOnlyHint when every step tool is read-only; omitted when none). Get the authoritative full schema of a chosen tool with describe_tool before executing it — it carries the same server, kind and annotations.

When the request declares a toolset (X-muster-Toolset header), every discovery meta-tool reads the catalogue intersected with it, call_tool refuses anything outside it (tool "<name>" is outside the toolset [<selectors>]), and an invalid toolset (empty, unknown preset, reserved toolset:, inline label:, more than 32 selectors, malformed) is an error result on every meta-tool call. Without the header nothing changes.

# Rank workflows by intent instead of guessing a pattern
filter_tools(query="deploy an app to a cluster", limit=5)

# Scope discovery to a labelled subset
filter_tools(labels={"category": "observability"})

# Page through a broad match
filter_tools(pattern="*workflow*", limit=25, offset=25)

Tool Execution¶

Meta-Tool	Description	Arguments
`call_tool`	Execute any tool by name. With `X-muster-Toolset` on the request, only tools inside the toolset can be called; others are refused naming the toolset (see Toolsets)	`{"name": "tool_name", "arguments": {...}}`

Example:

{
  "name": "call_tool",
  "arguments": {
    "name": "core_service_list",
    "arguments": {}
  }
}

Resource Access¶

Meta-Tool	Description	Arguments
`list_resources`	List available MCP resources	`{}`
`describe_resource`	Get resource metadata	`{"uri": "resource_uri"}`
`get_resource`	Read resource contents	`{"uri": "resource_uri"}`

Prompt Access¶

Meta-Tool	Description	Arguments
`list_prompts`	List available prompts	`{}`
`describe_prompt`	Get prompt details	`{"name": "prompt_name"}`
`get_prompt`	Execute a prompt	`{"name": "prompt_name", "arguments": {...}}`

Core Tools Overview¶

muster provides core built-in tools organized into functional categories. These are accessed via call_tool:

Configuration Tools - System configuration management
MCP Server Tools - MCP server lifecycle management
Service Tools - Service lifecycle (aggregator and MCP servers)
Workflow Tools - Workflow definition and execution management

Core tool annotations¶

Every core tool declares the MCP tool annotations readOnlyHint, destructiveHint, idempotentHint and openWorldHint, and list_tools / filter_tools / describe_tool report them like a downstream server's. The built-in read-only toolset preset therefore includes the read-only core tools and a workflow whose steps call only read-only tools stays read-only when one of them is a core tool.

Tool	readOnly	destructive	idempotent	openWorld	Why
`core_workflow_list`, `core_workflow_get`, `core_workflow_validate`, `core_workflow_available`, `core_workflow_execution_list`, `core_workflow_execution_get`	true	false	true	false	Read or validate; nothing changes.
`core_workflow_create`	false	false	false	false	Adds a definition.
`core_workflow_update`	false	true	true	false	Replaces a definition.
`core_workflow_delete`	false	true	false	false	Removes a definition.
`core_service_list`, `core_service_status`	true	false	true	false	Read.
`core_service_start`	false	false	true	false	Starts a stopped service; nothing is removed.
`core_service_stop`	false	true	true	false	Interrupts a running service.
`core_service_restart`	false	true	false	false	Interrupts and starts again.
`core_config_get`, `core_config_get_aggregator`	true	false	true	false	Read.
`core_config_update_aggregator`, `core_config_save`, `core_config_reload`	false	true	true	false	Replace the running or the persisted configuration.
`core_mcpserver_list`, `core_mcpserver_get`, `core_mcpserver_validate`	true	false	true	false	Read or validate.
`core_mcpserver_detect`	true	false	true	true	Probes a remote URL for its transport; reads only, but reaches beyond muster.
`core_mcpserver_create`	false	false	false	false	Adds a definition.
`core_mcpserver_update`	false	true	true	false	Replaces a definition.
`core_mcpserver_delete`	false	true	false	false	Removes a definition.
`core_events`	true	false	true	false	Read.
`core_auth_login`	true	false	true	true	Issues a sign-in link for the caller and changes nothing on the platform; the grant that follows lands in the caller's own session. Reaches the server's authorization server. A read-only agent keeps the ability to connect SSO-protected servers as the person.
`core_auth_logout`	false	false	true	false	Discards the caller's stored grant for a server — a write, nothing else is touched.

Workflow execution tools (workflow_<name>) declare nothing themselves; their readOnlyHint is derived from their steps.

Additional Tool Types¶

Beyond the core tools, muster also provides access to:

Dynamic Workflow Execution Tools - workflow_<name> tools generated from your workflow definitions
External Tools - Tools provided by your configured MCP servers (varies by installation)

Important: All tools below are accessed via call_tool(name="...", arguments={...}). They are not directly visible to MCP clients.

Quick Start¶

Basic Discovery Pattern¶

# Use meta-tools to discover
list_tools()                    # First page (50) of the catalogue; offset=50 for the next
filter_tools(pattern="core_*")  # Filter to core tools only

# Execute tools via call_tool
call_tool(name="core_service_list", arguments={})
call_tool(name="core_workflow_list", arguments={})
call_tool(name="workflow_<name>", arguments={...})

Common Operations¶

# Check system status
call_tool(name="core_service_list", arguments={})
call_tool(name="core_mcpserver_list", arguments={})

# Manage static services
call_tool(name="core_service_start", arguments={"name": "kubernetes"})
call_tool(name="core_service_status", arguments={"name": "kubernetes"})

# Execute workflows
call_tool(name="workflow_<your-workflow>", arguments={...})

Configuration Tools¶

Manage muster system configuration and aggregator settings. These tools allow you to read, modify, and persist configuration changes.

`core_config_get`¶

Get the complete current muster system configuration including aggregator, services, and other settings.

Arguments: None

Returns: Complete configuration object with all system settings

Example Request:

{
  "name": "core_config_get",
  "arguments": {}
}

Example Response:

{
  "Aggregator": {
    "Port": 8090,
    "Host": "localhost",
    "Transport": "streamable-http",
    "Enabled": true,
    "MusterPrefix": ""
  }
}

`core_config_get_aggregator`¶

Get aggregator-specific configuration details only.

Arguments: None

Returns: Aggregator configuration object

Example Request:

{
  "name": "core_config_get_aggregator",
  "arguments": {}
}

Example Response:

{
  "Port": 8090,
  "Host": "localhost",
  "Transport": "streamable-http",
  "Enabled": true,
  "MusterPrefix": ""
}

Use Cases: - Check current aggregator endpoint and settings - Verify aggregator is enabled before tool operations - Get connection details for external clients

`core_config_reload`¶

Reload configuration from configuration files, discarding any in-memory changes.

Arguments: None

Returns: Operation status and any errors encountered

Example Request:

{
  "name": "core_config_reload",
  "arguments": {}
}

Use Cases: - Refresh configuration after manual file edits - Revert in-memory changes to last saved state - Reload after external configuration updates

⚠️ Warning: This discards any unsaved configuration changes.

`core_config_save`¶

Save the current in-memory configuration to configuration files.

Arguments: None

Returns: Save operation status and file paths written

Example Request:

{
  "name": "core_config_save",
  "arguments": {}
}

Use Cases: - Persist configuration changes made through API - Create backup of current configuration - Ensure changes survive system restarts

`core_config_update_aggregator`¶

Update aggregator configuration settings.

Arguments: - aggregator (object, required) - Aggregator configuration object with the following properties: - Port (integer, optional) - Aggregator listen port (default: 8090) - Host (string, optional) - Aggregator bind host (default: "localhost") - Transport (string, optional) - Transport type ("streamable-http", "sse", "stdio") - Enabled (boolean, optional) - Whether aggregator is enabled - MusterPrefix (string, optional) - Prefix for muster core tools

Returns: Updated aggregator configuration

Example Request:

{
  "name": "core_config_update_aggregator",
  "arguments": {
    "aggregator": {
      "Port": 8080,
      "Host": "0.0.0.0",
      "Transport": "streamable-http",
      "Enabled": true
    }
  }
}

Use Cases: - Change aggregator listen port or host - Switch transport protocols (HTTP/SSE/stdio) - Enable/disable aggregator functionality - Configure tool prefixes

⚠️ Note: Changes take effect immediately but are not persisted until core_config_save is called.

MCP Server Tools¶

Manage MCP server definitions and lifecycle. These tools control the external MCP servers that provide additional capabilities like Kubernetes, Prometheus, or custom tooling.

Note: MCP servers are user-defined and not part of muster's core functionality. They are external processes that provide specialized tools and capabilities.

`core_mcpserver_list`¶

List all configured MCP servers with their definitions and metadata.

Arguments: None

Returns: Object containing array of MCP server definitions with configuration storage information

Example Request:

{
  "name": "core_mcpserver_list",
  "arguments": {}
}

Example Response:

{
  "mcpServers": [
    {
      "name": "my-custom-server",
      "type": "stdio",
      "autoStart": true,
      "description": "Custom MCP server for specialized tools",
      "command": ["my-server", "serve"],
      "env": {
        "API_KEY": "secret123"
      }
    }
  ],
  "mode": "filesystem",
  "total": 1
}

`core_mcpserver_create`¶

Create a new MCP server definition that can be started as a service.

Arguments: - name (string, required) - Unique server name (used as service identifier) - type (string, required) - Server type (stdio, streamable-http, or sse) - description (string, optional) - Human-readable description of server purpose - command (array of strings, optional) - Command executable and arguments (for stdio servers) - args (array of strings, optional) - Command line arguments (for stdio servers) - url (string, optional) - Server endpoint URL (for streamable-http and sse servers) - env (object, optional) - Environment variables as key-value pairs - headers (object, optional) - HTTP headers (for streamable-http and sse servers) - timeout (integer, optional) - Connection timeout in seconds - autoStart (boolean, optional) - Whether to start automatically on system startup

Returns: Created MCP server definition

Example Request:

{
  "name": "core_mcpserver_create",
  "arguments": {
    "name": "my-tools",
    "type": "stdio",
    "description": "Custom tool server for project management",
    "command": ["my-mcp-server", "--port", "3000", "--verbose"],
    "env": {
      "API_KEY": "abc123",
      "LOG_LEVEL": "debug"
    },
    "autoStart": true
  }
}

Use Cases: - Add custom MCP servers with specialized tools - Configure third-party MCP server integrations - Set up development or testing tool servers

`core_mcpserver_get`¶

Get detailed information about a specific MCP server definition.

Arguments: - name (string, required) - Name of the MCP server to retrieve

Returns: Complete MCP server definition object

Example Request:

{
  "name": "core_mcpserver_get",
  "arguments": {
    "name": "my-tools"
  }
}

Example Response:

{
  "name": "my-tools",
  "type": "stdio",
  "autoStart": true,
  "description": "Custom tool server for project management",
  "command": ["my-mcp-server", "--port", "3000", "--verbose"],
  "env": {
    "API_KEY": "abc123",
    "LOG_LEVEL": "debug"
  }
}

`core_mcpserver_update`¶

Update an existing MCP server definition. Only provided fields are updated.

Arguments: - name (string, required) - Name of the MCP server to update - type (string, optional) - Server type - description (string, optional) - Updated description - command (array of strings, optional) - New command and arguments - env (object, optional) - Updated environment variables (replaces existing) - autoStart (boolean, optional) - Auto-start setting - suspended (boolean, optional) - Desired lifecycle state: true stops the server's service and keeps it stopped; false (or omitted) resumes it - restartRequestedAt (string, optional) - RFC 3339 timestamp requesting a one-shot restart; processed once by the reconciler

Returns: Updated MCP server definition

Example Request:

{
  "name": "core_mcpserver_update",
  "arguments": {
    "name": "my-tools",
    "description": "Updated: Custom tool server with monitoring",
    "env": {
      "API_KEY": "new-key-456",
      "LOG_LEVEL": "info",
      "METRICS_ENABLED": "true"
    }
  }
}

Use Cases: - Update server configurations without recreating - Modify environment variables or command arguments - Change auto-start behavior

`core_mcpserver_delete`¶

Delete an MCP server definition. Server must be stopped before deletion.

Arguments: - name (string, required) - Name of the MCP server to delete

Returns: Deletion confirmation

Example Request:

{
  "name": "core_mcpserver_delete",
  "arguments": {
    "name": "my-tools"
  }
}

Use Cases: - Remove unused or deprecated MCP servers - Clean up test server configurations - Decommission replaced servers

⚠️ Warning: Ensure server is stopped before deletion. Use core_service_stop first if needed.

`core_mcpserver_validate`¶

Validate MCP server configuration without creating or modifying the server.

Arguments: - name (string, required) - Server name to validate - type (string, required) - Server type to validate - description (string, optional) - Description to validate - command (array of strings, optional) - Command to validate - env (object, optional) - Environment variables to validate - autoStart (boolean, optional) - Auto-start setting to validate

Returns: Validation result with any errors or warnings

Example Request:

{
  "name": "core_mcpserver_validate",
  "arguments": {
    "name": "test-server",
    "type": "stdio",
    "autoStart": true,
    "command": ["echo", "test"],
    "description": "Test server configuration"
  }
}

Use Cases: - Test server configurations before creation - Validate command existence and permissions - Check environment variable formats - Ensure name uniqueness

`core_mcpserver_detect`¶

Probe a remote MCP server URL to detect which transport it speaks (streamable-http or sse), so callers don't need to know it up front. Detection never fails on unreachable or unclassifiable servers: the result reports transport unknown instead, so callers can fall back to manual selection.

Arguments: - url (string, required) - Server endpoint URL to probe - headers (object, optional) - HTTP headers to send with the probe requests - timeout (integer, optional) - Overall detection timeout in seconds (default 10)

Returns: Detection result object: - url (string) - The probed endpoint - transport (string) - streamable-http, sse, or unknown - reachable (boolean) - Whether the server answered a probe at the HTTP level - requiresAuth (boolean) - Whether a probe was answered with a 401 challenge - serverName, serverVersion (string, optional) - Server info from a completed handshake - detail (string) - Human-readable explanation of the verdict

Example Request:

{
  "name": "core_mcpserver_detect",
  "arguments": {
    "url": "https://mcp.example.com/mcp"
  }
}

Example Response:

{
  "url": "https://mcp.example.com/mcp",
  "transport": "streamable-http",
  "reachable": true,
  "requiresAuth": false,
  "serverName": "example-server",
  "serverVersion": "1.4.2",
  "detail": "initialize handshake succeeded over streamable-http"
}

Use Cases: - Pre-select the transport in registration UIs once the user enters a URL - Verify a URL actually speaks MCP before registering it - Distinguish OAuth-protected servers (401 challenge) from unreachable ones

Service Tools¶

Manage the lifecycle of static services. The aggregator and MCPServer service wrappers are the only managed types.

Service Types: muster manages two types of services: - Aggregator: Core tool aggregation service - MCPServer: External MCP server processes

`core_service_list`¶

List all services with their current status and metadata.

Arguments: None

Returns: Object containing array of all services with detailed status information

Example Request:

{
  "name": "core_service_list",
  "arguments": {}
}

Example Response:

href="#__codelineno-24-1">{ "services": [ { "name": "mcp-aggregator", "service_type": "Aggregator", "state": "running", "health": "healthy", "metadata": { "port": 8090, "tools": 95, "servers_connected": 6 } }, { "name": "kubernetes", "service_type": "MCPServer", "state": "running", "health": "healthy", "metadata": { "autoStart": true, "command": ["mcp-kubernetes"] } } ], "total": 3 }

`core_service_start`¶

Start a specific service.

Arguments: - name (string, required) - Name of the service to start

Returns: Operation status and service state

Example Request:

{
  "name": "core_service_start",
  "arguments": {
    "name": "my-database"
  }
}

Use Cases: - Start stopped services - Restart failed services - Manually start services with autoStart=false

⚠️ Note: Static services (aggregator) may not support start operations.

Writes-as-caller: In Kubernetes mode, start on an MCPServer-backed service is a CR write with your own identity — it clears spec.suspended and, whenever the service is down, also writes spec.restartRequestedAt (the one-shot "make it run now" request), and the reconciler starts the service. Kubernetes RBAC authorizes the write and the apiserver audit log records you as the subject.

`core_service_stop`¶

Stop a specific service.

Arguments: - name (string, required) - Name of the service to stop

Returns: Operation status and service state

While an OAuth-protected MCPServer is stopped this way (spec.suspended: true), core_auth_login refuses it — Server '<name>' is deactivated (spec.suspended=true); activate it with core_service_start before signing in. — auth://status reports it disconnected with "suspended": true, and list_tools neither lists its tools nor names it under servers_requiring_auth. A session that had signed in before the stop finds its tools again after core_service_start without a new sign-in.

Example Request:

{
  "name": "core_service_stop",
  "arguments": {
    "name": "my-database"
  }
}

Use Cases: - Stop services for maintenance - Temporarily disable resource-intensive services - Clean shutdown before updates

⚠️ Warning: Stopping critical services (aggregator, MCP servers) may disrupt tool availability.

Writes-as-caller: In Kubernetes mode, stop on an MCPServer-backed service writes spec.suspended: true with your own identity; the reconciler stops the service and keeps it stopped until it is resumed.

`core_service_restart`¶

Restart a specific service (stop then start operation).

Arguments: - name (string, required) - Name of the service to restart

Returns: Operation status and final service state

Example Request:

{
  "name": "core_service_restart",
  "arguments": {
    "name": "kubernetes"
  }
}

Use Cases: - Apply configuration changes that require restart - Recover from service errors or hangs - Refresh connections or reinitialize state

Writes-as-caller: In Kubernetes mode, restart on an MCPServer-backed service writes spec.restartRequestedAt with your own identity; the reconciler restarts the service once and mirrors the processed value into status.lastRestartedAt. One attempt is made whether or not the endpoint answers: a restart that fails because the server is unreachable is recorded as processed too, and the service keeps retrying on its own reconnect backoff (status.nextRetryAfter); write a newer timestamp to request another restart.

`core_service_status`¶

Get current status information for a specific service.

Arguments: - name (string, required) - Name of the service to check

Returns: Detailed status including state, health, and runtime information

Example Request:

{
  "name": "core_service_status",
  "arguments": {
    "name": "mcp-aggregator"
  }
}

Use Cases: - Monitor service health and performance - Troubleshoot service issues - Get real-time status for dashboards

Workflow Tools¶

Manage workflow definitions and track executions. Workflows orchestrate multi-step processes with advanced features like templating, conditional execution, and output chaining.

Workflow Concept: Workflows are reusable, multi-step processes that execute tools in sequence, with support for conditional logic, variable passing between steps, and comprehensive execution tracking.

`core_workflow_list`¶

List all workflow definitions with their availability status.

Arguments: None

Returns: Object containing array of workflow definitions

Example Request:

{
  "name": "core_workflow_list",
  "arguments": {}
}

Example Response:

{
  "workflows": [
    {
      "name": "deploy-application",
      "description": "Deploy application with monitoring setup",
      "available": true
    },
    {
      "name": "backup-database",
      "description": "Backup database to remote storage",
      "available": false
    }
  ]
}

`core_workflow_create`¶

Create a new workflow definition with advanced step configuration.

Arguments: - name (string, required) - Unique workflow name - steps (array, required) - Array of workflow steps (minimum 1): - id (string, required) - Unique step identifier within workflow - tool (string, required) - Tool name to execute for this step - description (string, optional) - Human-readable step documentation - args (object, optional) - Tool arguments with templating support (inputs as {{ .input.<arg> }}, prior results as {{ .results.<step-id>.<field> }}) - condition (object, optional) - Conditional execution configuration: - tool (string, required) - Tool to call for condition evaluation - args (object, optional) - Arguments for condition tool - expect (object, optional) - Expected results for condition success - allow_failure (boolean, optional) - Whether step failure should not fail entire workflow - store (boolean, optional) - Whether to store step result in workflow results - args (object, optional) - Workflow argument schema with validation: - Each argument has: type, required, default, description - Supported types: string, integer, boolean, number, object, array - description (string, optional) - Workflow description

Returns: Created workflow definition

Example Request:

{
  "name": "core_workflow_create",
  "arguments": {
    "name": "deploy-with-monitoring",
    "description": "Deploy application and setup monitoring with health checks",
    "args": {
      "app_name": {
        "type": "string",
        "required": true,
        "description": "Application name to deploy"
      },
      "environment": {
        "type": "string",
        "default": "development",
        "description": "Target environment"
      },
      "health_check": {
        "type": "boolean",
        "default": true,
        "description": "Enable health checking"
      }
    },
    "steps": [
      {
        "id": "deploy",
        "tool": "x_kubernetes_apply",
        "description": "Deploy the application",
        "args": {
          "manifest": "{{ .input.manifest }}"
        }
      },
      {
        "id": "health_check",
        "tool": "core_service_status",
        "description": "Verify service is healthy",
        "condition": {
          "tool": "echo",
          "args": {
            "value": "{{ .input.health_check }}"
          },
          "expect": {
            "json_path": {
              "value": true
            }
          }
        },
        "args": {
          "name": "{{ .results.create_service.service_name }}"
        },
        "store": true
      }
    ]
  }
}

Use Cases: - Automate complex deployment processes - Create reusable operational procedures - Implement conditional logic workflows - Chain multiple service operations

`core_workflow_get`¶

Get detailed information about a specific workflow definition.

Arguments: - name (string, required) - Name of the workflow to retrieve

Returns: Complete workflow definition with all steps and configuration

Example Request:

{
  "name": "core_workflow_get",
  "arguments": {
    "name": "deploy-with-monitoring"
  }
}

Use Cases: - Inspect workflow configurations - Debug workflow step definitions - Understand argument requirements and step dependencies

`core_workflow_available`¶

Check if a workflow is available for execution (all required tools are present).

Arguments: - name (string, required) - Name of the workflow to check

Returns: Availability status with details about missing tools or dependencies

Example Request:

{
  "name": "core_workflow_available",
  "arguments": {
    "name": "deploy-with-monitoring"
  }
}

Use Cases: - Verify workflow dependencies before execution - Troubleshoot unavailable workflows - Check tool availability after system changes

`core_workflow_update`¶

Update an existing workflow definition. Only provided fields are updated.

Arguments: - name (string, required) - Name of the workflow to update - steps (array, optional) - Updated workflow steps (replaces all existing steps) - args (object, optional) - Updated argument schema - description (string, optional) - Updated description

Returns: Updated workflow definition

Example Request:

{
  "name": "core_workflow_update",
  "arguments": {
    "name": "deploy-with-monitoring",
    "description": "Updated: Enhanced deployment with advanced monitoring and rollback",
    "steps": [
      {
        "id": "deploy",
        "tool": "x_kubernetes_apply",
        "description": "Deploy the application",
        "args": {
          "manifest": "{{ .input.manifest }}"
        }
      }
    ]
  }
}

Use Cases: - Modify workflow behavior without recreation - Add new steps to existing workflows - Update step configurations or arguments

`core_workflow_delete`¶

Delete a workflow definition. Active executions are not affected.

Arguments: - name (string, required) - Name of the workflow to delete

Returns: Deletion confirmation

Example Request:

{
  "name": "core_workflow_delete",
  "arguments": {
    "name": "obsolete-workflow"
  }
}

Use Cases: - Remove obsolete or deprecated workflows - Clean up test workflows - Reorganize workflow library

⚠️ Note: Deleting a workflow does not affect running executions or execution history.

`core_workflow_validate`¶

Validate a workflow definition without creating it.

Arguments: - name (string, required) - Workflow name to validate - steps (array, required) - Workflow steps to validate - args (object, optional) - Argument schema to validate - description (string, optional) - Description to validate

Returns: Validation result with errors, warnings, and tool availability check

Example Request:

{
  "name": "core_workflow_validate",
  "arguments": {
    "name": "test-workflow",
    "steps": [
      {
        "id": "invalid_step",
        "tool": "nonexistent_tool",
        "args": {
          "invalid_template": "{{ .input.nonexistent_arg }}"
        }
      }
    ]
  }
}

Use Cases: - Test workflow configurations before creation - Validate step dependencies and tool availability - Check template syntax and argument references - Ensure workflow compatibility with current environment

`core_workflow_execution_list`¶

List workflow execution history with filtering options.

Arguments: - limit (number, optional, default: 50) - Maximum number of executions to return - offset (number, optional, default: 0) - Number of executions to skip (pagination) - status (string, optional) - Filter by execution status (running, completed, failed, cancelled) - workflow_name (string, optional) - Filter by specific workflow name

Returns: Array of workflow executions with metadata

Example Request:

{
  "name": "core_workflow_execution_list",
  "arguments": {
    "workflow_name": "deploy-with-monitoring",
    "status": "completed",
    "limit": 10
  }
}

Use Cases: - Monitor workflow execution history - Debug failed executions - Track deployment activities - Generate workflow usage reports

`core_workflow_execution_get`¶

Get detailed information about a specific workflow execution.

Arguments: - execution_id (string, required) - ID of the execution to retrieve - include_steps (boolean, optional, default: true) - Whether to include detailed step information - step_id (string, optional) - Get details for a specific step only

Returns: Complete execution details including step results, timing, and status

Example Request:

{
  "name": "core_workflow_execution_get",
  "arguments": {
    "execution_id": "exec_123456789",
    "include_steps": true
  }
}

Use Cases: - Debug workflow execution issues - Analyze step performance and timing - Retrieve execution outputs and results - Monitor long-running workflow progress

Dynamic Workflow Execution Tools¶

Important: For each workflow definition you create, muster automatically generates a corresponding execution tool named workflow_<workflow-name>. These tools accept the workflow's defined arguments and execute the workflow.

Note: Workflow execution tools depend on your workflow definitions and are not built into muster. Different muster installations will have different workflow execution tools based on their configured workflows.

How Workflow Execution Tools Work¶

Workflow Definition: You create workflows using core_workflow_create or by placing YAML files in .muster/workflows/
Tool Generation: muster automatically creates a corresponding workflow_<name> tool
Tool Discovery: The workflow tool appears in list_tools() output
Tool Execution: Execute via call_tool(name="workflow_<name>", arguments={...})

Example¶

If you create a workflow named deploy-webapp:

# .muster/workflows/deploy-webapp.yaml
name: deploy-webapp
description: "Deploy web application to Kubernetes"
args:
  app_name:
    type: string
    required: true
  environment:
    type: string
    default: "staging"
steps:
  - id: deploy
    tool: x_kubernetes_apply
    args:
      manifest: "{{ .input.app_name }}-manifest.yaml"

This generates a workflow_deploy-webapp tool that you execute via:

{
  "name": "call_tool",
  "arguments": {
    "name": "workflow_deploy-webapp",
    "arguments": {
      "app_name": "my-service",
      "environment": "production"
    }
  }
}

Workflow Tool Naming Convention¶

Workflow Name	Generated Tool Name
`deploy-webapp`	`workflow_deploy-webapp`
`connect-monitoring`	`workflow_connect-monitoring`
`auth-kubernetes`	`workflow_auth-kubernetes`

External Tools¶

External MCP tools come from your configured MCP servers (Kubernetes, Prometheus, Grafana, etc.). These are accessed the same way as core tools - via call_tool.

Naming Convention¶

External tools follow the pattern: x_<mcpserver-name>_<tool-name>

MCP Server	Tool	Full Name
`kubernetes`	`get_pods`	`x_kubernetes_get_pods`
`prometheus`	`query`	`x_prometheus_query`
`grafana`	`list_dashboards`	`x_grafana_list_dashboards`

Example: Kubernetes Tool¶

{
  "name": "call_tool",
  "arguments": {
    "name": "x_kubernetes_get_pods",
    "arguments": {
      "namespace": "default",
      "labelSelector": "app=my-service"
    }
  }
}

Discovering External Tools¶

Use meta-tools to discover what external tools are available:

# Page through the catalogue, external tools included (50 per page)
list_tools()
list_tools(offset=50)

# Filter to specific MCP server
filter_tools(pattern="x_kubernetes_*")

# Get details about a specific external tool
describe_tool(name="x_kubernetes_get_pods")

MCP tools reference¶

Meta-Tools (Primary Interface)¶

Tool Discovery¶

list_tools — the paged catalogue¶

describe_tool — the authoritative detail, and how to call it¶

filter_tools — the discovery tier¶

Tool Execution¶

Resource Access¶

Prompt Access¶

Core Tools Overview¶

Core tool annotations¶

Additional Tool Types¶

Quick Start¶

Basic Discovery Pattern¶

Common Operations¶

Configuration Tools¶

core_config_get¶

core_config_get_aggregator¶

core_config_reload¶

core_config_save¶

core_config_update_aggregator¶

MCP Server Tools¶

core_mcpserver_list¶

core_mcpserver_create¶

core_mcpserver_get¶

core_mcpserver_update¶

core_mcpserver_delete¶

core_mcpserver_validate¶

core_mcpserver_detect¶

Service Tools¶

core_service_list¶

core_service_start¶

core_service_stop¶

core_service_restart¶

core_service_status¶

Workflow Tools¶

core_workflow_list¶

core_workflow_create¶

core_workflow_get¶

core_workflow_available¶

core_workflow_update¶

core_workflow_delete¶

core_workflow_validate¶

core_workflow_execution_list¶

core_workflow_execution_get¶

Dynamic Workflow Execution Tools¶

How Workflow Execution Tools Work¶

Example¶

Workflow Tool Naming Convention¶

External Tools¶

Naming Convention¶

Example: Kubernetes Tool¶

Discovering External Tools¶

`list_tools` — the paged catalogue¶

`describe_tool` — the authoritative detail, and how to call it¶

`filter_tools` — the discovery tier¶

`core_config_get`¶

`core_config_get_aggregator`¶

`core_config_reload`¶

`core_config_save`¶

`core_config_update_aggregator`¶

`core_mcpserver_list`¶

`core_mcpserver_create`¶

`core_mcpserver_get`¶

`core_mcpserver_update`¶

`core_mcpserver_delete`¶

`core_mcpserver_validate`¶

`core_mcpserver_detect`¶

`core_service_list`¶

`core_service_start`¶

`core_service_stop`¶

`core_service_restart`¶

`core_service_status`¶

`core_workflow_list`¶

`core_workflow_create`¶

`core_workflow_get`¶

`core_workflow_available`¶

`core_workflow_update`¶

`core_workflow_delete`¶

`core_workflow_validate`¶

`core_workflow_execution_list`¶

`core_workflow_execution_get`¶