Skip to content

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.

Every client lists the meta-tools' full descriptions on connect, so they stay short: a summary line of at most 120 characters, then only what a model needs before a call. Meta-tools is generated from them (make tools-doc); this page carries the detail. Every meta-tool but call_tool is annotated read-only; call_tool, which runs whatever tool it is given, is annotated destructive and not idempotent. All are open-world: listing the catalogue first connects the session to the servers the person already granted.

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. The downstream tool's title (its own, else its annotations' title) and outputSchema, the contract of the structuredContent it returns, are forwarded as well. title, annotations and outputSchema are omitted when the tool does not set them. 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",
  "title": "List pods",
  "description": "List pods in a namespace.",
  "server": "kubernetes",
  "kind": "tool",
  "annotations": {"readOnlyHint": true},
  "inputSchema": {"type": "object", "properties": {"namespace": {"type": "string"}}},
  "outputSchema": {"type": "object", "properties": {"items": {"type": "array"}}},
  "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 the name, the description's first line and the rest of the description — a match weighs most in the name, less in the first line and least below it; ubiquitous verbs like list/get are down-weighted so the discriminating noun drives ranking, and function words such as the or how are dropped from the query unless it has no other word; a plural matches its singular, so policies finds policy), 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.

It also carries servers_requiring_auth when a sign-in would unlock a server whose tools the pattern could match once they are listed — every such server without a pattern; with x_slack_*, the slack server alone — each with name, status, auth_tool (core_auth_login), tool_prefix and, for a family member, family, as list_tools reports them. Neither the toolset (toolset_requiring_auth, see Toolsets) nor the other filters narrow it, and it is not paged. A tool you cannot find may be one of theirs: an agent that filters for *slack* before the person has signed in to Slack gets no tool and servers_requiring_auth: [{"name": "slack", "auth_tool": "core_auth_login", …}], and calls core_auth_login with server: slack.

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)

# A server the caller has not signed in to is named, not silently absent
filter_tools(pattern="x_slack_*")   # tools: [], servers_requiring_auth: [{"name": "slack", "auth_tool": "core_auth_login", …}]

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

Through muster agent --mcp-server, call_tool additionally takes timeout (seconds): how long the agent waits for this one call instead of its --timeout (default 5 minutes). The agent consumes the argument; the aggregator never sees it.

Example: 

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

Result: the first content item is a JSON envelope of the wrapped tool's result, {"isError", "content", "structuredContent", "_meta", "tool"}. Image and audio items are size-only in it and follow it as native content items with their payload. tool names what ran: name is the tool asked for, and for a tool an MCP server serves, server is that MCPServer and serverTool the server's own name for it; muster's core and workflow tools carry the name only. The same object is the call_tool result's _meta under muster.giantswarm.io/tool, for a client that reads _meta without parsing the envelope.

{"isError":false,"content":[{"text":"…","type":"text"}],"tool":{"name":"x_kubernetes_list_pods","server":"kubernetes","serverTool":"list_pods"}}

The Go agent client (muster agent, internal/agent) unwraps the envelope back into the wrapped tool's result and puts tool into its _meta under the same key; metatools.DispatchedToolFromMeta reads it.

A call that needs a sign-in

A call to a tool of a server the session has not signed in to is answered auth_required: isError: true, the sign-in link in the text and in structuredContent.authUrl, with status: "auth_required" and server. Through call_tool the same structuredContent is the result's own.

A client that declares URL mode elicitation (elicitation: {url: {}}) is asked to open the link instead, both for this answer and for the challenge of core_auth_login itself (MCP elicitation, URL mode), so the link never reaches the model as tool output:

Client's protocol version Answer
2026-07-28 or later, elicitation.url in the request's client capabilities resultType: "input_required" with one elicitation/create input request (mode: "url", url, message, and an elicitationId, the same for every answer with one link, which the 2026-07-28 schema does not define and rmcp requires) under the key muster_sign_in, and a requestState naming the server and the link. Retry the call, echoing requestState, once the person agreed to open the link: a retry whose inputResponses accept muster_sign_in waits until the sign-in's OAuth callback has run, on any replica, then runs the call. When the callback did not sign the session in (the person was refused, the server was suspended meanwhile, the connection failed), or did not run within 5 minutes, the retry gets the same answer with a new link. A retry whose inputResponses decline or cancel muster_sign_in runs nothing and gets a tool error without the link instead.
2025-11-25, elicitation.url declared at initialize JSON-RPC error -32042 (URLElicitationRequiredError) with the elicitation and its elicitationId, the same one for every call of that session answered with the same link. When the sign-in completes on the replica that answered, the session is sent notifications/elicitation/complete with that elicitationId; retry the call then. A retry before the sign-in completed gets the same error again: this protocol tells muster neither that the person accepted nor that they declined, so muster cannot hold the retry until the sign-in completes.
Any other The auth_required answer.

Only the sign-in answers muster issues are elicited: a backend result that has the same shape is returned unchanged. A server muster connects with the person's muster sign-in (token forwarding, token exchange) has no link to open, and keeps the auth_required answer.

Resource Access

Meta-Tool Description Arguments
list_resources List available MCP resources, each with its server {}
filter_resources Filter resources by URI pattern and/or source server, paged; a URI with a scheme carries no server prefix, so scope by server {"pattern": "board://*", "server": "...", "limit": 25}
describe_resource Get resource metadata, not its contents {"uri": "resource_uri", "server": "..."}
get_resource Read resource contents {"uri": "resource_uri", "server": "..."}

server on describe_resource and get_resource is needed only when several servers expose the same URI; list_resources reports the server of every entry.

Prompt Access

Meta-Tool Description Arguments
list_prompts List available prompts {}
filter_prompts Filter prompts by name pattern and/or source server, paged (names are x_<server>_<name>) {"pattern": "x_myserver_*", "limit": 25}
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:

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.
core_auth_status true false true true Reads the caller's state on every server; with auth_urls it issues the sign-in links core_auth_login would, which change nothing until the person completes them.

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

core_auth_login — reset_client_registration

reset_client_registration: true discards muster's stored dynamic client registration (RFC 7591) with the server's authorization server and registers anew before issuing the sign-in link. Use it when sign-ins fail with invalid_client although muster reports a stored registration: the authorization server has forgotten the client. Other users' tokens from that authorization server may need a fresh sign-in afterwards.

A client that gets a person ready before the agent needs them (a chat front-end right after its sign-in) reads the person's state on every server in one call. The answer is the auth://status document — servers[] with name, status, issuer, scope, auth_tool, error, suspended, the SSO flags — plus, per server:

  • kind: grant (a grant of the person's own, started with core_auth_login), sso (the muster sign-in, forwarded or exchanged; never a link) or none;
  • grant_scope: for a grant server, subject (the grant is the person's, every later session reuses it) or session (the session that completed it);
  • auth_url, with auth_urls: true, for every grant server in auth_required or reauth_required that is not suspended: the link core_auth_login would issue for it, with the same expiry and the same redirect parameter on /oauth/proxy/start. A server whose grant the person already holds is connected by the call and reported connected; one the login refuses carries the reason in error.

Issuing the links counts as one authentication attempt for the rate limit. Each link is a bearer link for the caller's session: show it to the person only.

{"name": "core_auth_status", "arguments": {"auth_urls": true}}
→ {"servers": [
    {"name": "github", "status": "auth_required", "kind": "grant", "grant_scope": "subject",
     "issuer": "https://github.com/login/oauth", "auth_tool": "core_auth_login",
     "auth_url": "https://muster.example.com/oauth/proxy/start?state=…"},
    {"name": "kubernetes", "status": "connected", "kind": "sso", "token_forwarding_enabled": true}
  ]}

Additional Tool Types

Beyond the core tools, muster also provides access to:

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) - displayName (string, optional) - Human-friendly name UIs show for the server, stored in the ui.giantswarm.io/display-name annotation next to the registered-by annotations muster stamps. Surrounding whitespace is trimmed; a blank value sets no annotation - 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 (for stdio servers; refused on a remote server) - headers (object, optional) - HTTP headers (for streamable-http and sse servers). In Kubernetes mode a value in Authorization, Proxy-Authorization, Cookie or X-API-Key is refused, as is a user name or password in url - headersFrom (array, optional) - Headers whose values muster reads from a Secret in the server's namespace when it connects, each {"name": "Authorization", "valueFrom": {"type": "Secret", "name": "<secret>", "key": "<key>"}} (for streamable-http and sse servers, Kubernetes mode). Output of the core tools shows the reference, never the value - timeout (integer, optional) - Connection timeout in seconds - progress (object, optional) - maxDuration (integer): seconds a tool call that reports progress may run in all; each progress notification restarts timeout up to it (at least timeout, at most 3600, default 3600) - 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",
    "displayName": "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. displayName, registeredBy and registeredByEmail carry the server's ui.giantswarm.io/ annotations and are omitted when unset; core_mcpserver_list returns the same fields per server

Example Request: 

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

Example Response: 

{
  "name": "my-tools",
  "displayName": "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 - displayName (string, optional) - Sets the ui.giantswarm.io/display-name annotation, trimmed; an empty or blank string removes it, and omitting it keeps the current one - 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; omitting it keeps the current one - 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 - displayName (string, optional) - Display name to validate, as on create - 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: 

{
  "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 and filter_tools neither list its tools nor name 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, optional) - Tool to call for condition evaluation - fromStep (string, optional) - Evaluate a previous step's result instead of calling a tool - args (object, optional) - Arguments for condition tool - expect (object, optional) - Expected results for condition success (success, jsonPath) - expectNot (object, optional) - Results that make the condition false - allowFailure (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

The field names are the Workflow CRD's, so a step copied from a manifest works unchanged. The snake_case spellings allow_failure, from_step, expect_not and json_path are deprecated aliases: still accepted, with a warning in the server log.

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

  1. Workflow Definition: You create workflows using core_workflow_create or by placing YAML files in .muster/workflows/
  2. Tool Generation: muster automatically creates a corresponding workflow_<name> tool
  3. Tool Discovery: The workflow tool appears in list_tools() output
  4. 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")