Local MCP

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:

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:

cd /path/to/your/project
nullspace docs install --agent all

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

export NULLSPACE_API_KEY=ns_live_...
export NULLSPACE_API_URL=https://api.your-nullspace-domain

Verify the CLI before connecting an agent:

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:

[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:

export NULLSPACE_API_KEY=ns_live_...
export NULLSPACE_API_URL=https://api.your-nullspace-domain
codex

Verify the server is configured:

codex mcp list

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

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:

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:

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

export NULLSPACE_API_KEY=ns_live_...
export NULLSPACE_API_URL=https://api.your-nullspace-domain
claude

Verify and approve the project MCP server:

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:

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:

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

export NULLSPACE_API_KEY=ns_live_...
export NULLSPACE_API_URL=https://api.your-nullspace-domain
cursor .

For Cursor CLI, verify the server and tools:

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:

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

nullspace mcp serve --transport http --host 127.0.0.1 --port 8765

Configure the client URL as:

http://127.0.0.1:8765/mcp

SSE:

nullspace mcp serve --transport sse --host 127.0.0.1 --port 8765

Configure the client URL as:

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.

Overview

Agent workspaces

Framework integrations

Local agent tooling

Install And Verify

Codex

Claude Code

Cursor

VS Code Or GitHub Copilot Agent Mode

Hosted Transports

Troubleshooting

​Install And Verify

​Codex

​Claude Code

​Cursor

​VS Code Or GitHub Copilot Agent Mode

​Hosted Transports

​Troubleshooting

Install And Verify

Codex

Claude Code

Cursor

VS Code Or GitHub Copilot Agent Mode

Hosted Transports

Troubleshooting