@symbiozai/mcp-setup

1-click installer for the SymbiozAI MCP server in your LLM-OS.

npx @symbiozai/mcp-setup

Supports Claude Desktop, Claude Code, Cursor, and Codex CLI on macOS, Linux, and Windows.

What it does

1. Detects your LLM-OS (Claude Desktop / Claude Code / Cursor / Codex).
2. Mints a unique MCP token for this device via the SymbiozAI API.
3. Non-destructively merges the SymbiozAI MCP server entry into your existing config — every other MCP server you already use is preserved (with a timestamped backup).
4. Validates the token against POST /api/v1/mcp/handshake-test.
5. Prints restart instructions + a first command suggestion.

Why this exists

Editing claude_desktop_config.json manually causes ~30–50% drop-off in the onboarding step 4. This CLI brings that drop-off down to 5–10% by handling the OS-specific paths, JSON merge, backup, and rollback automatically.

Requirements

• Node.js ≥ 18 (uses native fetch).
• A SymbiozAI tenant account (sign up at https://symbioz.ai).
• A short-lived tenant JWT — copy it from Console → Settings → "Copy JWT for CLI".

Headless / scripted usage

The Console onboarding wizard spawns this CLI in headless mode by pre-filling these env vars:

| Env var | Purpose | |---|---| | SYMBIOZAI_API_BASE | Override API base URL (default https://symbioz.ai). Format: scheme + host[:port] only — no path. The MCP URL is auto-derived as <base>/api/v1/mcp/rpc unless SYMBIOZAI_MCP_URL is explicitly set. Example: SYMBIOZAI_API_BASE=https://preview.symbioz.ai. | | SYMBIOZAI_API_URL | Legacy alias for SYMBIOZAI_API_BASE (pre-cv6.10). Kept for backward-compat — new code should prefer SYMBIOZAI_API_BASE. | | SYMBIOZAI_MCP_URL | Override MCP RPC URL verbatim (full URL with path). Only needed when the RPC path differs from the default /api/v1/mcp/rpc. | | SYMBIOZAI_JWT | Skip the JWT prompt | | SYMBIOZAI_MCP_TOKEN | Pre-minted MCP bearer (sk_mcp_*). Skips JWT prompt + mint round-trip. Used by Console wizard step 4. | | SYMBIOZAI_DEVICE_NAME | Skip the device name prompt | | SYMBIOZAI_LLM_OS | Skip LLM-OS selection (claude_desktop | claude_code | cursor | codex) | | MCP_SETUP_DEBUG | Print full stack traces on error |

Safety guarantees

• Backups: every existing config is copied to <path>.symbiozai-backup.<UTC-timestamp> before any write.
• Atomic writes: write-tmp → rename, never partial.
• Rollback: any I/O or JSON parse failure post-backup restores the original file automatically.
• No cleartext token cached: the bearer is held in memory only long enough to write the LLM-OS config, never logged or persisted on the user's machine.
• No shell out: no exec-style calls with user input. The only subprocess invocations are hardcoded which codex / which claude (or where ... on Windows) for binary detection.

Build + test (contributors)

npm install
npm run build
npm test

Exit codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | Unhandled error (bug — re-run with MCP_SETUP_DEBUG=1) | | 2 | Token API failure (auth, quota, network) | | 3 | Config edit failure (existing file invalid, I/O error) |

License

UNLICENSED — internal SymbiozAI asset. See repo root for usage terms.