> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Local MCP

> Connect Codex, Claude Code, Cursor, VS Code, or another MCP client to Nullspace CLI tools.

Nullspace ships a local Model Context Protocol server with the Python package.
It exposes the `nullspace` CLI as MCP tools so a local coding agent can create
machines, run commands, upload files, build templates, inspect volumes, and
stream lifecycle data without shelling out manually.

Use stdio for local coding agents. The agent starts `nullspace mcp serve` when
it needs tools, and the server process receives `NULLSPACE_API_KEY` and
`NULLSPACE_API_URL` from the MCP client configuration.

## Install And Verify

Install the SDK with CLI and MCP extras:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "nullspace-sdk[cli,mcp]==1.0.0"
```

If uv is already part of the project, `uv pip install
"nullspace-sdk[cli,mcp]==1.0.0"` is equivalent after the environment is active.

Install the local agent docs pack in the project where Claude Code or Codex
will run:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
cd /path/to/your/project
nullspace docs install --agent all
```

Set the hosted private-beta credentials in the shell that launches your agent:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
export NULLSPACE_API_KEY=ns_live_...
export NULLSPACE_API_URL=https://api.your-nullspace-domain
```

Verify the CLI before connecting an agent:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace --help
nullspace machine list --json
nullspace mcp serve --help
```

Do not run `nullspace mcp serve` as a separate background process for stdio
clients. Stdio clients launch it themselves and communicate over stdin/stdout.

Each leaf CLI command becomes a dotted MCP tool name. Hyphens normalize to
underscores:

| CLI command                       | MCP tool                          |
| --------------------------------- | --------------------------------- |
| `nullspace machine list`          | `nullspace.machine.list`          |
| `nullspace machine create`        | `nullspace.machine.create`        |
| `nullspace template build-status` | `nullspace.template.build_status` |
| `nullspace volume download-url`   | `nullspace.volume.download_url`   |

Tool schemas are generated from `nullspace schema`, and tool calls use the same
Click command path as the CLI.

## Codex

`nullspace docs install --agent codex` writes local docs to
`.nullspace/agent-docs/`, installs the Nullspace skill under
`.agents/skills/nullspace`, and writes a Codex MCP snippet at
`.nullspace/agent-docs/codex-config.toml`.

Codex reads MCP servers from `~/.codex/config.toml`. Add this block:

```toml theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
[mcp_servers.nullspace]
command = "nullspace"
args = ["mcp", "serve"]
env_vars = ["NULLSPACE_API_KEY", "NULLSPACE_API_URL"]
startup_timeout_sec = 10.0
tool_timeout_sec = 120.0
```

Then start Codex from a shell where the env vars are set:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
export NULLSPACE_API_KEY=ns_live_...
export NULLSPACE_API_URL=https://api.your-nullspace-domain
codex
```

Verify the server is configured:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
codex mcp list
```

Inside Codex, ask for a small read-only action first:

```text theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
Use the Nullspace MCP server to list my machines.
```

Codex should call `nullspace.machine.list`. If it does not, restart Codex after
editing `~/.codex/config.toml` and confirm the `nullspace` executable is on the
same `PATH` visible to Codex.

Codex can also add a stdio server with:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
codex mcp add nullspace -- nullspace mcp serve
```

After using the CLI add command, inspect `~/.codex/config.toml` and add
`env_vars`, `startup_timeout_sec`, and `tool_timeout_sec` if they are missing.

## Claude Code

`nullspace docs install --agent claude-code` writes local docs to
`.nullspace/agent-docs/`, adds managed Nullspace imports to `CLAUDE.md`, and
creates or updates `.mcp.json`. It also installs the Nullspace skill under
`.claude/skills/nullspace` for reusable Nullspace workflows.

For a project-scoped Claude Code setup, create `.mcp.json` in the project root:

```json theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
{
  "mcpServers": {
    "nullspace": {
      "command": "nullspace",
      "args": ["mcp", "serve"],
      "env": {
        "NULLSPACE_API_KEY": "${NULLSPACE_API_KEY}",
        "NULLSPACE_API_URL": "${NULLSPACE_API_URL}"
      }
    }
  }
}
```

This file is safe to commit because it references environment variables instead
of storing the actual API key.

Start Claude Code from a shell where the env vars are set:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
export NULLSPACE_API_KEY=ns_live_...
export NULLSPACE_API_URL=https://api.your-nullspace-domain
claude
```

Verify and approve the project MCP server:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
claude mcp list
claude mcp get nullspace
```

Inside Claude Code, run `/mcp` to inspect connected servers. Claude Code will
ask for approval before using project-scoped servers from `.mcp.json`.

Ask for a read-only first call:

```text theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
Use the nullspace MCP server to list my machines.
```

If the server fails to start, confirm `NULLSPACE_API_KEY` and
`NULLSPACE_API_URL` are present in the shell that launched `claude`.

## Cursor

Cursor uses `mcp.json` with an `mcpServers` object. Use a project-scoped file at
`.cursor/mcp.json`, or a global file at `~/.cursor/mcp.json`:

```json theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
{
  "mcpServers": {
    "nullspace": {
      "type": "stdio",
      "command": "nullspace",
      "args": ["mcp", "serve"],
      "env": {
        "NULLSPACE_API_KEY": "${env:NULLSPACE_API_KEY}",
        "NULLSPACE_API_URL": "${env:NULLSPACE_API_URL}"
      }
    }
  }
}
```

Restart Cursor after editing the file. If you use the desktop app, make sure it
can see the env vars. On macOS and Linux, launching Cursor from a terminal after
exporting the variables is the most direct check:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
export NULLSPACE_API_KEY=ns_live_...
export NULLSPACE_API_URL=https://api.your-nullspace-domain
cursor .
```

For Cursor CLI, verify the server and tools:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
cursor-agent mcp list
cursor-agent mcp list-tools nullspace
```

In Cursor chat, confirm `nullspace` appears in the available MCP tools, then
ask for a read-only action such as listing machines.

## VS Code Or GitHub Copilot Agent Mode

VS Code uses a different shape from Claude Code and Cursor: the top-level key is
`servers`, not `mcpServers`. Put this in `.vscode/mcp.json` for a workspace
setup:

```json theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
{
  "inputs": [
    {
      "type": "promptString",
      "id": "nullspace-api-key",
      "description": "Nullspace API key",
      "password": true
    },
    {
      "type": "promptString",
      "id": "nullspace-api-url",
      "description": "Nullspace API URL"
    }
  ],
  "servers": {
    "nullspace": {
      "type": "stdio",
      "command": "nullspace",
      "args": ["mcp", "serve"],
      "env": {
        "NULLSPACE_API_KEY": "${input:nullspace-api-key}",
        "NULLSPACE_API_URL": "${input:nullspace-api-url}"
      }
    }
  }
}
```

Open the command palette and run `MCP: List Servers` to confirm `nullspace`
starts. If you prefer env files, VS Code also supports `envFile`; keep any file
containing `NULLSPACE_API_KEY` out of git.

## Hosted Transports

Prefer stdio when the agent can spawn local commands. Use HTTP or SSE only when
the MCP client cannot spawn `nullspace` directly.

Streamable HTTP:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace mcp serve --transport http --host 127.0.0.1 --port 8765
```

Configure the client URL as:

```text theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
http://127.0.0.1:8765/mcp
```

SSE:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace mcp serve --transport sse --host 127.0.0.1 --port 8765
```

Configure the client URL as:

```text theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
http://127.0.0.1:8765/sse
```

Only bind to `0.0.0.0` when you have a separate access-control layer in front of
the server. The Nullspace MCP server uses your Nullspace API key and should be
treated as a privileged local tool.

## Troubleshooting

| Symptom                                  | Check                                                                                                                        |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Agent cannot find `nullspace`            | Use an absolute `command` path, or launch the agent from a shell where `which nullspace` succeeds.                           |
| MCP server starts but API calls fail     | Confirm `NULLSPACE_API_KEY` and `NULLSPACE_API_URL` are passed into the MCP server config, not only set in another terminal. |
| Tools are not visible after config edits | Restart the agent and use its MCP list command or UI to refresh connected servers.                                           |
| Cursor cannot resolve credentials        | Use `${env:NULLSPACE_API_KEY}` syntax and make sure Cursor was launched with that env var.                                   |
| VS Code config does not load             | Use top-level `servers`, not `mcpServers`, for `.vscode/mcp.json`.                                                           |
| Claude Code prompts for approval         | Approve the project-scoped server from `/mcp`; this is expected for `.mcp.json` files.                                       |

Prefer MCP when a local coding agent should perform Nullspace CLI actions.
Prefer the Python SDK when you are writing reusable application code, and prefer
direct CLI commands when you are doing a one-off terminal workflow.