Spacefast MCP

MCP server for publishing and managing Spacefast spaces from AI agents. It ships both as part of the spacefast CLI (sf mcp) and as the standalone @spacefast/mcp package. Every tool is a thin wrapper over the public Spacefast product API — the same engine as POST /v1/publish.

Spacefast has two MCP lanes:

• Cloud-hosted MCP at https://mcp.spacefast.com: for cloud agents; no local file access.
• On-Device MCP via sf mcp: for agents running on the user's machine; can publish local paths and use bounded workspace tools.

Usage

Cloud-only clients can use the hosted Streamable HTTP server:

https://mcp.spacefast.com

Hosted MCP requires an OAuth access token with mcp:tools plus the API scopes each tool needs: teams:read, spaces:read, spaces:write, and/or publish:write. Bearer and DPoP-bound tokens are supported. It exposes cloud-safe tools, a durable virtual workspace for generated files, and no access to the user's local filesystem.

Hosted Streamable HTTP sessions are recorded with an owner lease so production can route mcp-session-id traffic deterministically and clean up dead owners. If a request reaches a non-owner while the owner lease is still active, the server returns a routing conflict; if the owner lease has expired, the session is interrupted and the client should initialize again. Full executor-style cold rehydration requires an addressable session runtime that can persist and restore transport state in Postgres and route ownership through an equivalent session actor/service.

Preferred for checkout-aware work: let the agent config run the Spacefast CLI as On-Device MCP over stdio:

sf setup agent --agent auto --connect
sf mcp install --agent codex --mode local --transport stdio --connect

{
  "mcpServers": {
    "spacefast": {
      "command": "npx",
      "args": ["-y", "spacefast", "mcp"]
    }
  }
}

Embedded streamable HTTP is also available:

sf mcp install --mode local --transport http
sf mcp --transport http --port 3945 --http-token "$SPACEFAST_MCP_HTTP_TOKEN"

Tools

• search_docs — search agent docs, API guidance, CLI/MCP notes, safety rules, and recipes.
• publish — publish a local directory, file, archive, inline files, or a hosted virtual workspace path. Returns the live URL, immutable version URL, and (for anonymous publishes) a one-time claim link with expiry, plus a paste-ready share blurb.
• prepare_publish — create a manifest-based signed upload session for large/cloud-agent publishes without putting bytes in MCP JSON.
• resume_publish — refresh a manifest upload session when the token expires or more files need upload instructions.
• finalize_publish — finish a manifest upload session and return the final publish receipt.
• import_from_url — import an archive that already has an HTTPS URL.
• prepare_import_upload — create a signed archive-upload import session.
• resume_import_upload — fetch fresh signed archive-upload instructions for an existing import.
• finalize_import_upload — finish an upload-sourced archive import.
• claim — attach an anonymously published space to the authenticated account or a team.
• status — space state plus recent versions in one call.
• versions — list a space's immutable versions.
• diff — per-file diff between two versions, with unified patches.
• rollback — promote an earlier ready version back to live.
• logs — access or runtime log entries within the plan's retention window.
• build_logs — publish/finalize log entries for one version.
• execute — run sandboxed JavaScript code over the available tools through QuickJS; defaults to dry-run and can return approval_required for mutating code. Legacy JSON/JSONL workflows are still accepted with mode=workflow.
• resume — approve or deny a pending execute code-mode checkpoint with a single-use resume token.
• workspace_list/read/write/apply_patch/diff — hosted MCP uses the durable virtual workspace; On-Device MCP uses bounded local workspace files.
• workspace_manifest / workspace_export — hosted MCP only; inspect or export the durable virtual workspace for handoff between agents, sessions, or CI.
• workspace_import / workspace_import_url — hosted MCP only; load generated files or a signed HTTPS workspace bundle into the virtual workspace before review/publish.
• workspace_shell — hosted MCP only; runs bounded just-bash commands against /workspace and persists file changes.

For workspace edits, start with workspace_list / workspace_read, prefer workspace_apply_patch for known text changes, then call workspace_diff before reporting. Use hosted MCP for generated cloud-agent files, workspace imports, and handoffs; use On-Device MCP when the client must read or mutate the user's actual checkout.

Resources

Use resources for read-only orientation before tool calls. All API-backed resources are bounded, redacted, and return an available: false envelope instead of throwing when a credential lacks scope.

• spacefast://guide/agent-quickstart — compact lane choice and publish guidance.
• spacefast://account/current — authenticated subject, tenant grants, and visible teams.
• spacefast://teams/current / spacefast://teams/list — team context for publish/status work.
• spacefast://spaces/recent — recent spaces visible to the credential.
• spacefast://spaces/{spaceId} — one space's metadata.
• spacefast://spaces/{spaceId}/versions/recent — recent immutable versions.
• spacefast://spaces/{spaceId}/domains — assigned domains, when domain read scope is present.
• spacefast://spaces/{spaceId}/logs/summary — small access/runtime log sample.
• spacefast://policy/current — runtime scopes, boundaries, and tool approval posture.
• spacefast://workspace/manifest — hosted MCP virtual workspace manifest.
• spacefast://tools/catalog and spacefast://tools/{name} — compact tool catalog/detail.

Configuration

• SPACEFAST_AGENT_CONFIG — JSON config from the dashboard's agent account flow. The MCP server exchanges it for Better Auth OAuth access tokens with private_key_jwt.
• SPACEFAST_API_URL — API origin, defaults to https://api.spacefast.com.
• SPACEFAST_MCP_HTTP_TOKEN — required when local Streamable HTTP binds outside loopback and recommended for every local HTTP client.

Requests identify themselves with X-Spacefast-Client: spacefast-mcp/{version}. Attribution is never required for a request to succeed and carries no user-identifying data.