Concept Workspace CLI

Install Concept Workspace MCP into terminal agents and deploy Workspace hosted apps from a source folder.

Hosted Apps

Create or link an app folder:

npm exec --yes --package @concept-ai/workspace@latest -- \
  concept-workspace init demos/time-tracking --workspace <workspace-id-or-slug>

Deploy a new immutable version:

CONCEPT_WORKSPACE_API_KEY=wsk_live_... \
npm exec --yes --package @concept-ai/workspace@latest -- \
  concept-workspace deploy demos/time-tracking --workspace <workspace-id-or-slug> \
  --notes "fresh smoke deploy"

The deploy command archives the folder, uploads it through a signed URL, and returns JSON with the app id, version id, hosted URL, archive summary, and MCP tool hints. Use --app <id-or-slug> to relink or deploy an existing app, and --idempotency-key <key> for retry-safe automation.

Tail deploy logs, including provider build output, while keeping the final command result as JSON on stdout:

concept-workspace logs . --workspace <workspace-id-or-slug> \
  --app ai-operation-job-board --version wappver_... --watch
concept-workspace deploy . --workspace <workspace-id-or-slug> --watch

Manage runtime secrets without exposing values:

concept-workspace secret list . --workspace <workspace-id-or-slug>
printf %s "$DATABASE_URL" | concept-workspace secret set DATABASE_URL . \
  --workspace <workspace-id-or-slug>
concept-workspace secret set API_TOKEN . \
  --workspace <workspace-id-or-slug> --secret-from-env API_TOKEN
concept-workspace secret unset API_TOKEN . --workspace <workspace-id-or-slug>

After deploy, inspect through MCP:

workspace_app_status_get
workspace_app_logs_get
workspace_app_diagnostics_get
workspace_app_plan_get
workspace_app_version_source_list
workspace_app_version_generated_list
workspace_app_version_preview_get

Common deploy troubleshooting:

• auth_required: pass --api-key or set CONCEPT_WORKSPACE_API_KEY.
• workspace_required: pass --workspace <id-or-slug> or run from a linked folder with .concept/app.json.
• app_link_inaccessible: relink with concept-workspace init . --workspace <workspace> --app <app>.
• source_unchanged: change the source or pass --notes <text> to create a new version intentionally.
• Large archives warn above 100 MB. Use .gitignore or .dockerignore to keep build output out of the uploaded source archive.

MCP Installer

Codex

Run:

npm exec --yes --package @concept-ai/workspace@latest -- concept-workspace install codex

The installer writes the Codex MCP server entry with the required OAuth scopes:

[mcp_servers.concept]
url = "https://workspace-api.concept.dev/mcp"
scopes = ["openid", "profile", "email", "offline_access"]

After the config is written, the installer offers to run:

codex mcp login concept

You should not need to pass --scopes to codex mcp login.

Claude Code

Run:

npm exec --yes --package @concept-ai/workspace@latest -- concept-workspace install claude-code

The installer registers Concept Workspace with Claude Code. When the claude CLI is available, it delegates to:

claude mcp add --transport http --scope user concept https://workspace-api.concept.dev/mcp

If the claude CLI is not available, it falls back to writing Claude Code's user config with:

{
  "mcpServers": {
    "concept": {
      "type": "http",
      "url": "https://workspace-api.concept.dev/mcp"
    }
  }
}

Claude Code opens the OAuth sign-in flow the first time it uses a Workspace tool. The Claude Code config does not need a scopes field because Claude Code discovers scopes from Workspace MCP metadata.

Troubleshooting

If an MCP client was already running before install, quit and restart it so it reloads the updated config. If Codex still reports an OAuth refresh error after a clean install, run:

codex mcp logout concept
codex mcp login concept

Local tarball validation

Before publishing, validate the packed artifact through npx with temporary agent config directories:

tmp="$(mktemp -d)"
npm pack --workspace @concept-ai/workspace --pack-destination "$tmp"

CODEX_HOME="$tmp/codex" \
  npx --yes --package "$tmp"/concept-ai-workspace-0.1.2.tgz \
  concept-workspace install codex --no-login --yes
CODEX_HOME="$tmp/codex" codex mcp get concept

CODEX_HOME="$tmp/codex" \
  npx --yes --package "$tmp"/concept-ai-workspace-0.1.2.tgz \
  concept-workspace install codex --dry-run --no-login --yes

CLAUDE_CONFIG_DIR="$tmp/claude" \
  npx --yes --package "$tmp"/concept-ai-workspace-0.1.2.tgz \
  concept-workspace install claude-code --no-cli --yes

Inspect $tmp/codex/config.toml for the Workspace MCP URL plus required Codex OAuth scopes. Inspect $tmp/claude/.claude.json for mcpServers.concept.type = "http", the Workspace MCP URL, and no scopes field.

If the claude CLI is installed, also validate CLI delegation:

CLAUDE_CONFIG_DIR="$tmp/claude-cli" \
  npx --yes --package "$tmp"/concept-ai-workspace-0.1.2.tgz \
  concept-workspace install claude-code --yes
CLAUDE_CONFIG_DIR="$tmp/claude-cli" claude mcp get concept

Publishing

Publish the next npm package release:

npm run test --workspace @concept-ai/workspace
npm pack --dry-run --workspace @concept-ai/workspace
npm publish --workspace @concept-ai/workspace --access public

This package is the canonical npm installer for Concept Workspace.