# MCP (/docs/integrations/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 [#install-in-claude-code] ```bash title="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 [#generic-mcp-configuration] ```json title="mcp.json" { "mcpServers": { "crownest": { "command": "npx", "args": ["-y", "@crownest/mcp"], "env": { "CROWNEST_API_KEY": "cn_live_..." } } } } ``` ## Tools [#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 [#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. 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 [#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 [#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. ```text 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 [#local-development] Use the source build when working from this repository or testing changes before a package release: ```bash title="Terminal" pnpm --filter @crownest/mcp build CROWNEST_API_KEY=cn_live_... node packages/mcp/dist/index.js ``` Focused package checks: ```bash title="Terminal" pnpm --filter @crownest/mcp test pnpm --filter @crownest/mcp typecheck ``` ## Next steps [#next-steps] * [TypeScript SDK Code](/docs/sdk/code) - the Code Run surface used by `run_code`. * [Capability matrix](/docs/api/capabilities) - every MCP, CLI, and SDK operation in one table. * [Agent patterns](/docs/guides/agent-patterns) - repeatable multi-step recipes across MCP, CLI, and SDK surfaces. * [Commands](/docs/sdk/commands) - process execution and streaming logs. * [Artifacts](/docs/sdk/artifacts) - durable outputs that MCP hosts can download. * [Previews](/docs/sdk/previews) - HTTP services exposed from a Sandbox.