Tools Reference

The Nullstone MCP server exposes tools dynamically — each Nullstone CLI command becomes one MCP tool at startup. Running a newer CLI version adds new tools automatically.

Naming convention

Tools are named by joining the CLI command path with underscores:

CLI command	MCP tool name
nullstone profile	nullstone_profile
nullstone stacks list	nullstone_stacks_list
nullstone envs new	nullstone_envs_new
nullstone modules describe	nullstone_modules_describe

Clients may add their own namespace prefix (e.g. Claude Code presents tools as mcp__nullstone__stacks_list).

Discovering the tool list

The simplest way to see exactly what's available in your installed version:

nullstone --help

Every subcommand listed there is also an MCP tool. Drill in for a specific command's flags — those become the tool's input schema:

nullstone deploy --help

Common tool groups

Identity and configuration

Tool	Purpose
nullstone_profile	Return the active user, org, and API endpoint. Safe diagnostic call.
nullstone_set_org	Switch the active org for the session.
nullstone_workspaces_select	Select a specific workspace (stack + env + block) for subsequent commands.

Discovery (read-only)

Tool	Purpose
nullstone_stacks_list	List stacks in the org.
nullstone_apps_list	List applications.
nullstone_blocks_list	List all blocks of every type.
nullstone_envs_list	List envs in a stack.
nullstone_status	Status of an app or block.
nullstone_outputs	Terraform-style outputs for a block.
nullstone_logs	Tail or fetch logs for an app.
nullstone_modules_find	Search the registry — give it a term like "postgres" or "fargate".
nullstone_modules_describe	Full metadata for a module: category, vars, connections, capabilities.

Environment lifecycle

Tool	Purpose	Destructive?
nullstone_envs_new	Create a new env (including previews).	No
nullstone_envs_up	Provision an env's infrastructure.	No (additive)
nullstone_envs_down	Tear down an env's infrastructure.	Yes
nullstone_envs_delete	Delete env records entirely.	Yes

Infra operations

Tool	Purpose	Destructive?
nullstone_plan	Show the proposed infra change.	No
nullstone_apply	Apply an infra change.	Potentially
nullstone_up	Convenience: plan + apply for a block/env.	Potentially
nullstone_launch	Provision a brand-new block.	No
nullstone_wait	Wait for an async operation to complete.	No

Application operations

Tool	Purpose
nullstone_push	Push an artifact to the registry.
nullstone_deploy	Deploy an app version to an env.

Module authoring

Tool	Purpose
nullstone_modules_package	Package a local module for publishing.
nullstone_modules_publish	Publish a packaged module to the registry.
nullstone_modules_register	Register a module without publishing source.
nullstone_iac_generate	Generate IaC scaffolding for a block.
nullstone_iac_test	Test IaC configuration against a module's schema.

Safety flags

For destructive tools, Nullstone recommends:

• Require your MCP client to prompt before invoking (default in Claude Code).
• Scope the API key so those tools fail if the agent tries to use them outside approved contexts.
• Prefer nullstone_plan before nullstone_apply / nullstone_up so the agent can summarize the change before confirming.

Future: generated reference

This page covers the common tool surface. A complete, version-pinned reference will be generated from the MCP server's own tool manifest in a future release — track nullstone-io/mcp-server#TBD.