MCP Tools

The Knot MCP server exposes a set of built-in tools that AI assistants and MCP clients can use to manage spaces, templates, stack definitions, and the files and commands inside running spaces. The exact tools available to a given caller depend on the user’s permissions. Plugins can expose further tools — see Plugins → MCP Tools.

Write-capable tools (create, update, delete, start, stop, share, transfer, run, write) require approval when called from the Knot web assistant. Read-only tools run without a confirmation prompt. External MCP clients connected to /mcp are not prompted.

Tool Visibility

Each tool is either native or on-demand. This controls how it appears to MCP clients:

Visibility	Behaviour
Native	Always present in `tools/list` and can be called directly by name.
On-demand	Hidden from the default `tools/list` to keep context usage low. Discover with `tool_search(query=...)` and run with `execute_tool(name=..., arguments=...)`. To list every tool directly instead, send the `X-MCP-Show-All: true` header or use `knot mcp --show-all`.

See Finding Tools for how clients use on-demand tools.

To remove built-in tools, list their names in disable_builtin_tools under [server.mcp] (flag --mcp-disable-builtin-tools, environment variable KNOT_MCP_DISABLE_BUILTIN_TOOLS):

    
[server.mcp]
disable_builtin_tools = ["run_command", "delete_space"]

To replace the built-in set entirely, point server.mcp_tools_path at a directory of tool definitions; knot then loads tools from that directory instead of its own.

Spaces

Tool	Description	Visibility
`list_spaces`	List all spaces for the current user, including status and sharing details.	Native
`get_space`	Retrieve detailed space information, including configuration and status.	Native
`create_space`	Create a new development space, optionally with custom fields and start-on-create.	Native
`update_space`	Update properties of an existing space (name, description, shell, custom fields).	On-demand
`delete_space`	Permanently delete a space and all its data.	On-demand
`start_space`	Start a space.	Native
`stop_space`	Stop a space.	Native
`restart_space`	Restart a space.	Native

Templates

list_templates returns active templates only, including each template’s custom field definitions (name and description) so callers have what they need to set custom fields when creating a space. create_template builds a template from a simplified, wizard-style spec — the AI provides an image, environment variables, ports, resources, and feature toggles, and knot writes the native Nomad HCL or container YAML for it (the same model as the UI spec wizard). Full template editing — health checks, schedules, advanced spec features — still happens through the Knot web UI or CLI.

Tool	Description	Visibility
`list_templates`	List active space templates, including their custom field definitions.	On-demand
`get_template`	Get one template’s full custom field definitions (names, types, required flags, defaults and valid option values), to see exactly what to send when creating a space.	On-demand
`create_template`	Create a space template from a container image using a simplified spec (image, env vars, ports, memory, CPU, features); knot builds the native spec.	On-demand

Stack Definitions

Stack definitions (called stack templates in the web UI) are blueprints that describe a set of components (template bindings) and the dependencies between them. They are instantiated into running stacks via create_stack. Definitions are authored through the Knot web UI or CLI; MCP exposes read access so AI assistants can discover what’s available to instantiate.

Tool	Description	Visibility
`list_stack_definitions`	List stack definitions available to the current user, including their components.	On-demand

Stacks

A stack is a deployed instance — a group of spaces that share a stack name, typically created from a stack definition.

Tool	Description	Visibility
`list_stacks`	List stack instances by grouping spaces with the same stack name.	On-demand
`create_stack`	Instantiate a stack from a stack definition: creates the spaces, wires up dependencies, and applies port forwards.	On-demand
`start_stack`	Start all spaces in a stack in dependency order.	On-demand
`stop_stack`	Stop all spaces in a stack in reverse dependency order.	On-demand
`restart_stack`	Restart all spaces in a stack.	On-demand
`delete_stack`	Delete all spaces in a stack. Running spaces must be stopped first; the server checks every space before deleting any, so the call is all-or-nothing.	On-demand

Files

Operations on files inside a running space. Searches run in the space’s agent, so file contents don’t leave the space.

Tool	Description	Visibility
`read_file`	Read a file from a running space, optionally a 1-based line range.	Native
`write_file`	Write content to a file in a running space: overwrite (the default), append or prepend.	Native
`edit_file`	Replace one occurrence of a string in a file; fails unless the search text appears exactly once.	On-demand
`find`	Find files and directories by name, type or size; recursive by default.	On-demand
`grep`	Search file contents with a regex or literal pattern, returning matching lines with paths and line numbers.	On-demand
`sed_extract`	Extract regex capture groups from a file, or files under a directory. Read-only.	On-demand
`sed_replace`	Replace every literal occurrence of a string in a file, or files under a directory.	On-demand
`sed_replace_pattern`	Replace every regex match in a file, or files under a directory; the replacement can reference capture groups as `${1}` or `${name}`.	On-demand

Commands

Operations that execute inside a running space. list_scripts is the discovery companion to run_script — call it first to see which named scripts are available.

Tool	Description	Visibility
`list_scripts`	List active scripts available to run via `run_script`. Filters to the current zone and the caller’s groups.	On-demand
`run_command`	Execute a command in a running space. Returns its `output`, `success` and `exit_code`, plus `error` when it fails; a failed command’s output is returned too. Each of `arguments` reaches the command unchanged.	Native
`run_script`	Execute a named script in a running space.	Native

Skills

Skills are markdown knowledge documents that give AI assistants context and procedures (see Skills).

Skills are not exposed as a tool: they are served over the MCP skills extension, skills/list and skills/get, with each skill’s content readable via resources/read on its skill:// URI.

Pools

Pools keep a target number of identical spaces running from a template. See Space Pools for the full lifecycle and port routing details.

Tool	Description	Visibility
`list_pools`	List pools with utilization, lease settings and members, or get one pool by name.	Discovery
`create_pool`	Create a pool from a template with a desired space count, optional startup script, optional start-on-create, optional member leases (`lease_max_time`, `lease_max_extensions`), and custom field values for every member.	Discovery
`delete_pool`	Delete a stopped pool and all its member spaces.	Discovery
`start_pool`	Start a stopped pool: starts all member spaces and creates new ones if needed.	Discovery
`stop_pool`	Stop a running pool: stops all member spaces without deleting them.	Discovery
`set_pool_size`	Change the desired number of spaces in a pool. The sweep loop handles scaling.	Discovery
`acquire_pool_member`	Check out a member of a lease-enabled pool for exclusive use, optionally for a set `time` and waiting up to `wait` for a free member. Returns the lease with the held space’s name and ID.	Discovery
`extend_pool_lease`	Extend the lease held on a pool member; limited by the pool’s maximum number of extensions.	Discovery
`release_pool_member`	Release a held pool member back to the pool, or with `destroy` delete it so a fresh replacement is created.	Discovery
`list_pool_leases`	List the leases held on a pool’s members, active and draining.	Discovery

Tool Discovery

These tools are provided by the MCP server itself to support the on-demand discovery pattern. They are available on the discovery endpoint (/mcp/discovery).

Tool	Description
`tool_search`	Search for available tools by keyword or description. Returns matching tool names and schemas.
`execute_tool`	Execute a tool that was found via `tool_search`. Takes the tool name and an arguments object.

What’s Next

MCP - Enabling and configuring the MCP server
Remote MCP Servers - Connecting external MCP servers
Skills - Authoring knowledge content for AI assistants

Navigation