MCP

@crownest/mcp is a stdio MCP server for CrowNest. It lets MCP hosts create Sandboxes, run Commands, run Python Code, read and write Workspace files, create and download Artifacts, manage Previews, inspect Code Contexts, and perform safe API-key and Project operations without adding CrowNest-specific integration code to the host.

The server is a host-process tool bridge. CROWNEST_API_KEY stays in the MCP host environment and is not passed into Sandbox runtime environment variables.

The server also sends MCP startup instructions that describe the lazy default Sandbox model, /workspace, Code Run output promotion, usage discovery, Sandbox TTL semantics, retry/idempotency routing, and best-effort session cleanup.

Install in Claude Code

Terminal

claude mcp add crownest -e CROWNEST_API_KEY=cn_live_... -- npx -y @crownest/mcp

Set CROWNEST_API_URL only when targeting a non-production CrowNest API.

Generic MCP configuration

mcp.json

{
  "mcpServers": {
    "crownest": {
      "command": "npx",
      "args": ["-y", "@crownest/mcp"],
      "env": {
        "CROWNEST_API_KEY": "cn_live_..."
      }
    }
  }
}

Tools

The server registers these tools:

Tool	Description
`run_code`	Runs Python code in a Sandbox, using the lazy default when `sandbox_id` is omitted. Outputs can become Artifacts.
`list_code_contexts`	Lists live Code Contexts in a Sandbox.
`get_code_context`	Inspects a live Code Context in a Sandbox.
`run_command`	Runs a Command in a Sandbox, defaulting cwd to `/workspace`, and returns stdout/stderr plus ids.
`get_command`	Inspects Command status, exit code, and timing by Command id.
`cancel_command`	Cancels a Command by Command id with graceful or force mode.
`stream_command_logs`	Reads the currently available bounded Command log buffer.
`create_sandbox`	Creates an additional Sandbox for the current MCP server session without changing the lazy default.
`list_sandboxes`	Lists live Sandboxes visible to the configured API Key.
`get_usage`	Reads compute usage, credits, quota buckets, and MCP-session Sandbox state.
`get_sandbox`	Inspects a Sandbox by id or the current lazy default Sandbox.
`extend_sandbox`	Resets a live Sandbox TTL from now; expired Sandboxes cannot be revived.
`kill_sandbox`	Kills a server-created Sandbox. Killing the default Sandbox makes the next default call create a new one.
`write_file`	Writes UTF-8 text to a Workspace path under `/workspace`.
`read_file`	Reads UTF-8 text from a Workspace path.
`list_files`	Lists files in a Workspace path, defaulting to `/workspace`.
`delete_file`	Deletes a file or empty directory from the Workspace.
`move_file`	Moves or renames a Workspace file.
`make_directory`	Creates a Workspace directory.
`stat_file`	Inspects Workspace file metadata.
`create_artifact`	Creates a durable Artifact from a Workspace file.
`list_artifacts`	Lists Artifacts for a Sandbox.
`get_artifact`	Inspects Artifact metadata by Artifact id.
`download_artifact`	Downloads an Artifact by id and returns base64 content plus content type.
`delete_artifact`	Deletes an Artifact by Artifact id.
`create_preview`	Creates a Preview for a Sandbox HTTP service. Token auth mode returns a one-time Preview token.
`list_previews`	Lists Previews for a Sandbox.
`get_preview`	Inspects a Preview by Preview id.
`revoke_preview`	Revokes a Preview by Preview id.
`list_api_keys`	Lists API Key metadata without returning secret key values.
`revoke_api_key`	Revokes an API Key by API Key id.
`create_project`	Creates a Project for isolating Sandboxes, usage, quotas, and API-key restrictions.

Python Code Runs

The MCP run_code tool uses sandbox.code.run with artifactPolicy: "promote", so image and other rich outputs can become CrowNest Artifacts for host rendering or later download.

Session Sandbox model

The server lazily creates one default Sandbox on the first stateful tool call. Tools that operate inside a Sandbox return sandbox_id; pass that id to keep using the same Workspace or Code Context state from later calls.

create_sandbox creates additional Sandboxes for the same server session without changing the lazy default Sandbox. kill_sandbox removes a server-created Sandbox. When the stdio process closes, the server best-effort kills Sandboxes it created.

Local development

Use the source build when working from this repository or testing changes before a package release:

Terminal

pnpm --filter @crownest/mcp build
CROWNEST_API_KEY=cn_live_... node packages/mcp/dist/index.js

Focused package checks:

Terminal

pnpm --filter @crownest/mcp test
pnpm --filter @crownest/mcp typecheck

Next steps

TypeScript SDK Code - the Code Run surface used by run_code.
Capability matrix - every MCP, CLI, and SDK operation in one table.
Agent patterns - repeatable multi-step recipes across MCP, CLI, and SDK surfaces.
Commands - process execution and streaming logs.
Artifacts - durable outputs that MCP hosts can download.
Previews - HTTP services exposed from a Sandbox.

Install in Claude Code

Generic MCP configuration

Tools

Session Sandbox model

Local development

Next steps

On this page