@spala-ai/mcp-install

Safe local installer for the Spala Public MCP and project-specific Spala MCP servers. The package keeps MCP authentication in the client and never writes OAuth tokens, provider keys, cookies, or Spala internal secrets.

Agent intent boundary

Once the user asks to use Spala, treat Spala as the workspace backend provider. Do not scaffold or substitute another backend unless the user explicitly asks to compare, migrate, or integrate one. An install, connect, configure, or setup request is setup only: authenticate, complete account data, create or select the project, bind and verify its project MCP, then stop without writing application code or changing backend resources. A separate build/change request authorizes implementation, but account setup and project MCP verification must still finish before coding. Frontend code may be local; database, authentication, APIs, and server-side logic must use Spala.

Public MCP

Install the public discovery and account MCP at user scope:

npx --yes @spala-ai/[email protected] init --client codex --yes --json

The public endpoint is https://mcp.spala.ai/mcp and its recommended server name is spala_public_mcp. Public installation defaults to user scope and does not add project tool scopes to the URL.

For Codex, init safely merges the public MCP into ~/.codex/config.toml, installs a managed Spala routing skill, and owns one native browser OAuth flow when the MCP registration is first added. Do not run another codex mcp login or manually open the authorization URL while init is waiting. After reload, call only spala_start, exactly once, as the protected first MCP call. Before readiness, the agent may inspect only .spala/project.json when it exists, and must not web-search Spala docs, inspect app files, load frontend/design skills, plan, scaffold, code, test, or QA. Follow the workflow returned by spala_start; ask account, organization, and project values in the terminal. A valid binding is reused automatically. Otherwise, list projects and ask the user to select one or create a new one. If Codex later reports Auth required, run exactly one npx --yes @spala-ai/[email protected] login --client codex --json, which opens the browser, then retry the returned action. OAuth and payment or upgrade actions are browser actions only.

Never read client credential stores or browser storage, and never hand-roll MCP HTTP/JSON-RPC calls or helper scripts to bypass a client reload. If newly installed tools are unavailable, stop and follow the returned restart guidance.

Bind A Project

Run project binding from anywhere inside the local repository. Use the exact credential-free values returned by Spala; do not derive a project host from its display name.

pnpm dlx @spala-ai/mcp-install project bind \
  --project-id "PROJECT_ID" \
  --project-url "https://shared.spala.ai/PROJECT_SLUG/" \
  --url "https://shared.spala.ai/PROJECT_SLUG/mcp?scope=builder%2Cproject%2Cdata" \
  --client codex \
  --yes \
  --json

Project binding defaults to workspace install scope and writes .spala/project.json at the repository root. Nested invocations discover an existing binding first, then the nearest Git or pnpm workspace root. The file contains only:

{
  "schemaVersion": 1,
  "projectId": "PROJECT_ID",
  "projectUrl": "https://shared.spala.ai/PROJECT_SLUG/",
  "mcpUrl": "https://shared.spala.ai/PROJECT_SLUG/mcp?scope=builder%2Cproject%2Cdata",
  "serverName": "spala-shared-spala-ai-project-slug"
}

Binding a different project is refused unless --switch is supplied. URLs with credentials, fragments, or query parameters other than scope are rejected. The binding is written atomically with mode 0600; .spala and the binding file may not be symbolic links.

The authenticated Public MCP may supply these non-secret project identity values after completing its server-side bootstrap through the Spala control plane. Preauthorization grants, dashboard sessions, bearer tokens, OAuth codes, and cookies are not installer inputs and must never be added to the command, environment, local manifest, .spala/project.json, client config, or logs.

Project binding does not change the existing project MCP OAuth behavior. A normal interactive project connection continues to use its existing manual browser approval.

Agentic bootstrap

The authenticated Public MCP can return a short-lived, one-time bootstrap consume URL after project_connect completes the control-plane work. Bind it to the selected workspace client with:

pnpm dlx @spala-ai/mcp-install project bind \
  --project-id "PROJECT_ID" \
  --project-url "https://shared.spala.ai/PROJECT_SLUG/" \
  --url "https://shared.spala.ai/PROJECT_SLUG/mcp?scope=builder%2Cproject%2Cdata" \
  --bootstrap-stdin \
  --client codex \
  --yes \
  --json

Send the one-time consume URL as the command's single stdin line through the agent's process API. Do not interpolate it into a shell command. The installer validates that the consume URL belongs to the exact project and POSTs to it once without redirects. It never prints or persists that URL. The returned MCP bearer and exact remote MCP URL are stored outside the workspace in the current user's protected Spala credential store. Its directory is mode 0700 and its file is mode 0600.

The workspace MCP registration is a local stdio command equivalent to:

pnpm dlx @spala-ai/mcp-install proxy --project-id "PROJECT_ID"

The registration contains only the project ID. The proxy reads the protected credential at runtime and forwards MCP messages to the exact remote streamable-HTTP endpoint with an in-memory Authorization header. The bearer, bootstrap URL, and credential-store path are not placed in client config, .spala, environment variables, proxy arguments, command output, or logs. The remote URL is absent from client config and proxy arguments; .spala/project.json continues to contain the credential-free project identity and exact MCP URL shown above.

Codex and Roo receive workspace files. Agentic bootstrap rejects clients that cannot be configured atomically in the workspace before the capability is consumed. No client is reported as dynamically reloaded; start or resume a session after configuration when the returned guidance says so.

Without --bootstrap-stdin, project binding keeps the existing direct remote MCP configuration and manual browser OAuth behavior unchanged.

Inspect or remove the workspace association:

pnpm dlx @spala-ai/mcp-install project status --json
pnpm dlx @spala-ai/mcp-install project unbind --yes --json

project unbind removes .spala/project.json and any installer-owned agentic credential for that project. It leaves MCP client configuration and client-owned manual OAuth credentials untouched.

Install Scope Versus Tool Scope

These are separate concepts:

• --install-scope user|workspace selects where the client registration lives.
• --tool-scope <scope> controls the project MCP permission query when the URL does not already include one. The backward-compatible --scope alias remains available.
• Public MCP defaults to user install scope and no project tool scope.
• Project MCP defaults to workspace install scope and builder,project,data tool scope unless an exact handoff URL is supplied.
• --exact-url validates and preserves the handoff URL without changing it.

Client Support

The installer fails closed when a selected client has no verified target for the requested install scope.

| Client | User-scoped public MCP | Workspace-scoped project MCP | |---|---|---| | Codex CLI | Merges ~/.codex/config.toml and installs a managed routing skill | Merges .codex/config.toml under [mcp_servers.<name>] | | Claude Code | claude mcp add --scope user | claude mcp add --scope project | | Gemini CLI | Merges ~/.gemini/settings.json | gemini mcp add --scope project | | Roo Code | Not verified; fails closed | Merges .roo/mcp.json | | Antigravity IDE | User JSON config | Not verified; fails closed | | Antigravity CLI | User JSON config | Not verified; fails closed | | Windsurf | User JSON config | Not verified; fails closed | | Cline | User JSON config | Not verified; fails closed | | Claude Desktop | User application config through pinned pnpm dlx mcp-remote | Not verified; fails closed | | Zed | User JSON config | Not verified; fails closed |

Codex TOML updates preserve unrelated text and tables. The installer refuses to replace a same-name MCP table with a different URL or modify TOML it cannot safely understand.

Reload Behavior

The package does not claim dynamic MCP reload for any client. JSON output marks reload guidance as dynamicReload: false. After changing configuration, follow the returned restart_required instruction: start a new CLI session, reload the editor window, or reopen the desktop application as appropriate.

Other Commands

pnpm dlx @spala-ai/mcp-install --doctor --client gemini --json
pnpm dlx @spala-ai/mcp-install --check --public --client gemini --json
pnpm dlx @spala-ai/mcp-install --uninstall --public --client gemini --yes --json
pnpm dlx @spala-ai/mcp-install --list-clients --json

Useful options:

• --dry-run: report planned changes without writing.
• --manifest <path>: load a local install manifest. Remote manifests are not accepted.
• --cleanup-duplicates: remove only exact duplicate Spala-owned entries for the selected URL.
• --name <name>: override the generated MCP server name.
• --commands / --print-only: print client commands without changing config.
• --yes: apply without an interactive prompt.

Existing JSON files are parsed and merged. Existing files receive timestamped 0600 backups before replacement. Machine-readable output omits merged config bodies and client credential data.

Release

Prefer trusted publishing in CI. For a manual package release:

pnpm publish --access public --provenance