Skip to main content
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 sandboxes, 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]==0.1.9"
If uv is already part of the project, uv pip install "nullspace-sdk[cli,mcp]==0.1.9" 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 sandbox 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 commandMCP tool
nullspace sandbox listnullspace.sandbox.list
nullspace sandbox createnullspace.sandbox.create
nullspace template build-statusnullspace.template.build_status
nullspace volume download-urlnullspace.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 sandboxes.
Codex should call nullspace.sandbox.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 sandboxes.
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 sandboxes.

​
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

SymptomCheck
Agent cannot find nullspaceUse an absolute command path, or launch the agent from a shell where which nullspace succeeds.
MCP server starts but API calls failConfirm 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 editsRestart the agent and use its MCP list command or UI to refresh connected servers.
Cursor cannot resolve credentialsUse ${env:NULLSPACE_API_KEY} syntax and make sure Cursor was launched with that env var.
VS Code config does not loadUse top-level servers, not mcpServers, for .vscode/mcp.json.
Claude Code prompts for approvalApprove 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.