Nullstone MCP Server
The Nullstone MCP Server is a Model Context Protocol server that exposes every Nullstone CLI command as an MCP tool. AI agents — Claude Code, Claude Desktop, Cursor, and any other MCP client — use it to take action against your Nullstone org on your behalf.
What it exposes
The server discovers tools dynamically at startup by parsing nullstone --help, so it always matches your installed CLI version. Every CLI command becomes a tool. Common groupings:
| Category | Example tools | Purpose |
|---|---|---|
| Identity | nullstone_profile, nullstone_set_org | Who am I? which org? |
| Discovery | nullstone_stacks_list, nullstone_apps_list, nullstone_envs_list, nullstone_blocks_list, nullstone_modules_find, nullstone_modules_describe | Read org state and module registry. |
| Infrastructure | nullstone_up, nullstone_apply, nullstone_plan, nullstone_envs_up, nullstone_envs_down, nullstone_envs_new, nullstone_envs_delete | Create / update / destroy infra. |
| Application | nullstone_push, nullstone_deploy, nullstone_launch, nullstone_wait, nullstone_status, nullstone_logs, nullstone_outputs | Build, ship, observe. |
| Authoring | nullstone_modules_package, nullstone_modules_publish, nullstone_modules_register, nullstone_iac_generate, nullstone_iac_test | Module authoring workflows. |
The full tool list depends on your CLI version — see the tools reference.
How it works
┌────────────────┐ MCP tool call ┌────────────────┐ CLI invocation ┌────────────────┐
│ Claude / IDE │ ────────────────▶ │ Nullstone MCP │ ─────────────────▶ │ nullstone CLI │ ──▶ Nullstone API
└────────────────┘ └────────────────┘ └────────────────┘- Startup — the server runs
nullstone --helprecursively, learns every subcommand and flag. - Registration — each discovered command becomes an MCP tool: name derived from the command path, input schema derived from flags, description from help text.
- Invocation — on tool call, the server maps tool inputs to CLI flags, executes
nullstone …, and returns stdout/stderr to the client.
When to use MCP vs CLI vs API
| Use case | Surface |
|---|---|
| AI agent driving a task end-to-end | MCP |
| Human running one-off commands | CLI |
| CI pipelines and custom tooling | CLI or REST API |
| Agent needs structured output (JSON) | MCP — tools return CLI output as-is, so prefer commands that already support --format=json |
Safety model
The MCP exposes every CLI command, including destructive ones (envs_down, envs_delete, apply). The MCP server itself does not enforce an allow/deny list — that's the responsibility of:
- The API key. Scope the key used by the MCP to what the agent is allowed to do.
- The MCP client. Claude Code, for example, prompts before invoking any tool unless you allowlist it. Use this to require confirmation on destructive operations.
For agent-driven deploys to production, we recommend a dedicated service-account API key with least-privilege scope, plus an explicit "do not auto-approve" policy in the client.