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, run Workspace Runs, and run API-key and Project operations.

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 currently registers 62 MCP tools:

Tool	Description
`run_code`	Runs interpreter code in a Sandbox. Outputs can become Artifacts.
`get_agent_context`	Returns bounded, non-secret session guidance for MCP hosts that do not expose resources.
`run_command`	Runs a Command in a Sandbox. Waits for completion by default; `background: true` returns at once.
`create_sandbox`	Creates an additional Sandbox with an optional create-time `network_policy`.
`kill_sandbox`	Kills the default, server-created, or explicitly supplied visible Sandbox.
`write_file`	Writes UTF-8 text to a Workspace path under `/workspace`.
`write_file_bytes`	Writes base64 bytes to a Workspace path.
`read_file`	Reads UTF-8 text from a Workspace path.
`read_file_bytes`	Reads Workspace file bytes as base64 with size bounds.
`get_file_download_url`	Creates or reuses a short-lived Workspace file download URL.
`list_files`	Lists files in a Workspace path, defaulting to `/workspace`.
`download_artifact`	Downloads an Artifact by id and returns base64 content plus content type.
`get_artifact_download_url`	Creates or reuses a short-lived Artifact download URL.
`list_sandboxes`	Lists live Sandboxes visible to the configured credential.
`list_templates`	Lists curated, smoke-tested Templates and their capabilities.
`get_template`	Gets one curated Template by user-facing slug.
`get_usage`	Reads compute usage, spend metadata, quota buckets, and MCP-session Sandbox state.
`get_sandbox`	Inspects a Sandbox by id or the current lazy default Sandbox.
`set_sandbox_ttl`	Resets a live Sandbox TTL countdown from now; expired Sandboxes cannot be revived.
`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.
`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.
`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.
`create_code_context`	Creates a live Code Context for stateful Code Runs.
`list_code_contexts`	Lists live Code Contexts in a Sandbox.
`get_code_context`	Inspects a live Code Context in a Sandbox.
`delete_code_context`	Deletes a live Code Context.
`list_api_keys`	Lists API Key metadata without returning secret key values.
`get_api_key`	Reads API Key metadata by id without returning the secret key value.
`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.
`list_projects`	Lists visible Projects.
`create_workspace_run`	Creates a durable Workspace Run record.
`upload_workspace_run_archive`	Uploads a small gzipped tar archive through the CrowNest API.
`create_workspace_run_archive_transfer`	Creates a short-lived staged archive upload target and redacts header values in the tool result.
`upload_workspace_run_archive_transfer`	Uploads bytes to the staged archive transfer target remembered by the MCP session.
`finalize_workspace_run_archive`	Finalizes a staged archive transfer for a Workspace Run.
`start_workspace_run`	Starts archive extraction and Command execution.
`get_workspace_run`	Reads Workspace Run status and metadata.
`list_workspace_runs`	Lists visible Workspace Runs with optional filters.
`replay_workspace_run_events`	Replays bounded Workspace Run events after an optional sequence number.
`cancel_workspace_run`	Cancels an active Workspace Run.
`get_workspace_run_evidence`	Reads the terminal Evidence Bundle for a Workspace Run.
`create_workspace_run_matrix`	Creates a first-class Workspace Run Matrix and its ordered cells.
`upload_workspace_run_matrix_archive`	Uploads the one immutable archive shared by every Matrix cell.
`start_workspace_run_matrix`	Atomically reserves capacity and starts bounded Matrix fan-out.
`get_workspace_run_matrix`	Reads Matrix parent, cell, and aggregate status.
`list_workspace_run_matrices`	Lists visible Workspace Run Matrices with cursor pagination.
`replay_workspace_run_matrix_events`	Replays bounded Matrix lifecycle events after an optional sequence number.
`cancel_workspace_run_matrix`	Cancels active and scheduled Matrix cells.
`get_workspace_run_matrix_evidence`	Reads aggregate Matrix evidence with links to child Evidence Bundles.

Prompts and resources

MCP discovery advertises:

Resource crownest://agent/context for bounded non-secret context.
Prompt crownest_workspace_run for archive-based create/upload/start/replay/evidence flows.
Prompt crownest_sandbox_session for lower-level Sandbox, Command, Code Context, file, Artifact, and Preview work.

The public server card at https://crownest.dev/.well-known/mcp/server-card.json and public agent context at https://crownest.dev/.well-known/agent-context.md publish the same tools, prompts, and resource.

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. Passing an explicit visible Sandbox id to a tool adopts that Sandbox for the session, but process-exit cleanup only kills Sandboxes the MCP server created. kill_sandbox can still kill an explicitly supplied visible Sandbox when the caller has permission.

Workspace Run flow

MCP exposes Workspace Runs as primitive lifecycle tools. Use the CLI workspace-runs run-archive command for a one-shot local convenience flow; use MCP when the model needs retryable steps.

create_workspace_run({ "template": "python-node", "command": "pnpm test" })
create_workspace_run_archive_transfer({ "workspace_run_id": "wsr_...", "sha256": "...", "size_bytes": 12345 })
upload_workspace_run_archive_transfer({ "workspace_run_id": "wsr_...", "upload_id": "upl_...", "content_base64": "..." })
finalize_workspace_run_archive({ "workspace_run_id": "wsr_...", "upload_id": "upl_...", "sha256": "...", "size_bytes": 12345 })
start_workspace_run({ "workspace_run_id": "wsr_..." })
replay_workspace_run_events({ "workspace_run_id": "wsr_...", "after_seq": 0, "limit": 100 })
get_workspace_run_evidence({ "workspace_run_id": "wsr_..." })

Workspace Run create, upload, transfer, finalize, and start tools accept idempotency_key. Event replay is bounded; call it again with the last seen sequence number to continue.

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.

On this page