@cantinasecurity/apex-cli 0.1.27 → 0.1.28

package/.claude/skills/apex-cli/SKILL.md

@@ -11,9 +11,11 @@ This skill is bundled with Apex CLI and can be installed into the current reposi
 
 ## Instructions
 
-Use Apex through the MCP server when the `apex-*` tools are available.
+Use Apex through the MCP server when the `apex-*` tools are available. The tools installed by `apex setup` use the local stdio server and device login.
 
-For serverless, cron, or other HTTP-only integrations, use the hosted Apex REST API instead of CLI or stdio MCP. Its scan trigger, status, and findings contract is documented at https://ai.cantina.xyz/docs/apex-api.
+For a production MCP client that does not need local filesystem access, use the hosted Streamable HTTP endpoint at `https://ai.cantina.xyz/mcp`. Read the organization service key from `APEX_SERVICE_KEY` and supply it only as `Authorization: Bearer <TOKEN>`; never put the raw key in a tool argument, result, prompt, source file, or log. The hosted tools are `apex-credits`, `apex-workspaces`, `apex-scan`, `apex-status`, `apex-cancel-scan`, `apex-findings`, and `apex-workspace-findings`.
+
+For serverless, cron, or other explicit HTTP/JSON integrations, use the hosted Apex REST API instead of CLI or local stdio MCP. The hosted MCP and REST contract is documented at https://ai.cantina.xyz/docs/apex-api.
 
 For on-prem or other non-default Apex hosts, make sure the CLI or MCP server runs with `APEX_BASE_URL` set to the external HTTPS Bedrock origin before auth or provider connection flows.
 
@@ -55,11 +57,12 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 - `apex-trial-status` is MCP-only; do not invoke it as a CLI command. In a CLI-only flow, use the `claimDeadline` returned by `apex redeem <code> --json` without repeating or persisting the secret code.
 - After a guest scan, tell the user to run `apex claim` on the same machine before that returned claim deadline. If the deadline is unavailable or uncertain, do not guess or start a replacement login; run `apex claim` and let the server validate the proof.
 - Claim moves the guest workspace, scans, and findings into the currently selected Cantina workspace when the account can run scans there. Personal workspace owners receive the trial in their existing workspace instead of a duplicate. If the selected workspace cannot run scans, tell the user to switch to one that can and retry before the claim deadline.
-- Service-key management has no MCP tools. Never ask a user to paste a service key into a prompt, and never place one in an MCP call, tool result, source file, or log.
+- Service-key creation, listing, and revocation have no MCP tools. Never ask a user to paste a service key into a prompt, and never place one in a tool argument, tool result, source file, or log. Hosted MCP clients may read it from a secret-backed environment variable for the HTTP Authorization header.
 - If a user explicitly needs a new service key, tell them to run `apex login` if needed, then run `apex service-key create --name <name> --scope <scope[,scope]>` directly in their own terminal. Use only the required scopes: `scans:create` to query credit availability or trigger, `scans:read` to poll status, and `findings:read` to retrieve findings. A P1-only adapter can use `--scope scans:read,findings:read`; omitting `--scope` grants all three. The CLI automatically selects the company when only one is available and prompts when there are several; use `--company <id-or-handle>` to skip that prompt or resolve a non-interactive command. Service-key commands never initiate login, and the secret is shown once.
-- For a headless HTTP adapter, read the service key from the secret-backed `APEX_SERVICE_KEY` environment variable, send it as a bearer token to `/api/apex/v1`, and redact it from errors and logs. A service key does not authenticate CLI or MCP commands; those use device login. Do not shell out to `apex` or launch MCP from the adapter.
+- For a hosted MCP client, connect to `https://ai.cantina.xyz/mcp` and send `APEX_SERVICE_KEY` as a Bearer header. The service key authenticates hosted MCP, but not the local CLI or stdio MCP; those use device login.
+- For a headless REST adapter, read the service key from the secret-backed `APEX_SERVICE_KEY` environment variable, send it as a bearer token to `/api/apex/v1`, and redact it from errors and logs. Do not shell out to `apex` or launch local MCP from the adapter.
 - Hosted API integrations can call `GET /api/apex/v1/credits` with `scans:create` scope to inspect the organization's current standard, audit, and Lite balances and effective scan-type availability. Treat the response as a point-in-time snapshot; scan creation remains authoritative.
-- Hosted API v1 remote-repository scans require the GitHub repository to be linked to an active Apex workspace and do not create or mutate workspaces; use optional `workspaceId` to disambiguate matches and treat zero or ambiguous matches as HTTP `409` setup errors. Local or non-Git scans use the documented source-upload flow, which can create or reuse a workspace; send `generateThreatModel: true` for the first scan of a newly created local workspace.
+- Hosted remote-repository scans require the GitHub repository to be connected to the service key's Apex organization. They reuse a linked active workspace or create and link one when no match exists; use optional `workspaceId` to disambiguate multiple matches and treat explicit workspace/repository mismatches as HTTP `409` setup errors. Local or non-Git REST scans use the documented source-upload flow; send `generateThreatModel: true` for the first scan of a newly created local workspace.
 - Hosted scan triggers require `Idempotency-Key`. Reuse one stable key only for an identical transport/timeout/5xx retry. After correcting a definitive 4xx response, or for any new intended scan, use a new key.
 - Use `--non-interactive` and `--no-open` for automation-friendly CLI calls.
 - Use `--json` whenever structured output is helpful.
@@ -86,6 +89,7 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 
 ## Examples
 
+- Connect a production MCP client: configure `https://ai.cantina.xyz/mcp` as a Streamable HTTP server and source its Bearer token from `APEX_SERVICE_KEY`, then verify `apex-credits` without printing the credential.
 - Redeem a supplied trial code: run `apex redeem <code> --json` in a terminal, continue with MCP only after a `redeemed` or `idempotent` outcome, then check `apex-trial-status` and remind the user about `apex claim` after findings only while `claimAvailable` remains true.
 - Start a scan for the current repository or directory: run `apex-doctor`, bind a workspace if needed, then call `apex-scan`.
 - Start a Lite scan: call `apex-scan` with `mode: "lite"` after confirming beta access and provider-backed sources.

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Cantina agent plugins for security review workflows.",
-    "version": "0.1.27"
+    "version": "0.1.28"
   },
   "plugins": [
     {
@@ -14,10 +14,10 @@
       "source": {
         "source": "npm",
         "package": "@cantinasecurity/apex-cli",
-        "version": "0.1.27"
+        "version": "0.1.28"
       },
       "description": "Run Apex security scans and review findings from Claude Code.",
-      "version": "0.1.27",
+      "version": "0.1.28",
       "author": {
         "name": "Cantina",
         "email": "support@cantina.xyz"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-cli",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Run Apex security scans and review findings from Claude Code.",
   "author": {
     "name": "Cantina",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-cli",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Run Apex security scans and review findings from Codex.",
   "author": {
     "name": "Cantina",

package/.mcp.claude.json

@@ -5,7 +5,7 @@
       "args": [
         "-y",
         "-p",
-        "@cantinasecurity/apex-cli@0.1.27",
+        "@cantinasecurity/apex-cli@0.1.28",
         "apex-mcp"
       ],
       "env": {

package/.mcp.codex.json

@@ -4,7 +4,7 @@
     "args": [
       "-y",
       "-p",
-      "@cantinasecurity/apex-cli@0.1.27",
+      "@cantinasecurity/apex-cli@0.1.28",
       "apex-mcp"
     ],
     "env": {

package/MARKETPLACE.md

@@ -13,7 +13,7 @@ This package is prepared as both a Claude Code plugin and a Codex plugin. The pu
 The plugin MCP configs launch the pinned npm CLI package with:
 
 ```bash
-npx -y -p @cantinasecurity/apex-cli@0.1.27 apex-mcp
+npx -y -p @cantinasecurity/apex-cli@0.1.28 apex-mcp
 ```
 
 That keeps marketplace installs independent of a user's global `apex` install.

package/README.md

@@ -152,30 +152,30 @@ unclaimed local trial proof so `apex claim` can still use it.
 Agent-safe copy/paste prompt (substitute the issued code):
 
 ```text
-Install and run Cantina Apex CLI 0.1.27 to start one free standard security scan of this repository immediately.
+Install and run Cantina Apex CLI 0.1.28 to start one free standard security scan of this repository immediately.
 
 Use this trial code only where <TRIAL_CODE> appears below: SPBT-DEVREL-XXXXXXXX
 
 Run the commands yourself from the repository root; do not stop after setup or only explain the steps. Use terminal CLI commands only. Do not use an Apex MCP tool or run `apex setup`, `apex mcp`, `apex login`, `apex-auth-start`, or `apex-auth-wait`. Never use `--replace` or `--force`.
 
 Use this exact command prefix for every Apex command:
-  npx -y -p @cantinasecurity/apex-cli@0.1.27 apex
+  npx -y -p @cantinasecurity/apex-cli@0.1.28 apex
 
 1. Before redeeming, confirm every command will use the same persistent, user-accessible machine or container, HOME, filesystem, and repository root. Confirm Node.js 20+ and npx are available. If `APEX_BASE_URL` is set, continue only when its origin is `https://ai.cantina.xyz`. Run the exact prefix with `--help` and continue only if help lists both `redeem` and `claim`. If any check fails, STOP before sending the code; do not install system packages.
 2. Redeem, with at most one response-loss recovery retry:
-     npx -y -p @cantinasecurity/apex-cli@0.1.27 apex redeem <TRIAL_CODE> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.28 apex redeem <TRIAL_CODE> --json
    This terminal command is the only allowed tool call containing the code. Never echo or restate the code, store it in a file or environment variable, put it in a URL or MCP call, or include it in your response. Parse the JSON from stdout only; do not merge stderr into stdout, because npm may write warnings to stderr. Continue when the command exits 0 and stdout is JSON with `redeemed: true` and `outcome` equal to `redeemed` or `idempotent`. `idempotent` means the existing guest session resumed and it may already own a workspace. If and only if the first attempt ends with an ambiguous transport/connection failure or an interrupted/missing response and no typed server error code, retry this exact same command once on the same machine, HOME, and repository root. Never retry a typed server rejection and never make more than one recovery retry. If the allowed retry does not return a successful JSON outcome, STOP.
 3. Immediately start exactly one scan; do not wait for another instruction:
-     npx -y -p @cantinasecurity/apex-cli@0.1.27 apex scan --mode standard --non-interactive --no-open --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.28 apex scan --mode standard --non-interactive --no-open --json
    The CLI validates the complete guest local archive before it reserves a workspace. An unbound renamed checkout may recover only the sole empty guest workspace when no explicit workspace name was supplied. On any error or nonzero exit, STOP. After a successful scan JSON response, inspect `localPersistence.workspaceBindingSaved`. If it is `false`, the server scan already started: capture and report `binding.lastScanId`, then STOP; do not run status or findings until local repository permissions are repaired. Otherwise capture `binding.lastScanId` from the JSON as <SCAN_ID>; if it is absent, STOP.
 4. About every 60 seconds, poll that exact scan:
-     npx -y -p @cantinasecurity/apex-cli@0.1.27 apex status --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.28 apex status --scan <SCAN_ID> --json
    Read `progress.progress.status`. Wait while it is `created`, `pending`, `queued`, `starting`, `running`, `in_progress`, or `processing`. Continue on `completed`. STOP on `failed`, `cancelled`, a missing or unknown status, or a command failure.
 5. Fetch that exact scan's findings:
-     npx -y -p @cantinasecurity/apex-cli@0.1.27 apex findings --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.28 apex findings --scan <SCAN_ID> --json
    On success, summarize findings by severity, most severe first, including identifier, title, status, and confidence. This command does not return file locations, so do not invent them. On failure, STOP.
 6. Do not claim automatically. Tell me the claim deadline from step 2 and remind me to run this exact command myself from the same repository root, machine, and HOME:
-     npx -y -p @cantinasecurity/apex-cli@0.1.27 apex claim
+     npx -y -p @cantinasecurity/apex-cli@0.1.28 apex claim
    It may open a browser so I can create or sign in to a Cantina account and keep the results. Claim moves the trial into the currently selected Cantina workspace when I can run scans there, or into my existing personal workspace. If the selected workspace cannot run scans, tell me to switch to one that can and retry before the claim deadline.
 
 Never paste raw command transcripts. For any failure, report only the step, exit code, and sanitized error. Redact the trial code and every `apex_at_`, `apex_rt_`, or `apex_ct_` value from all reports.
@@ -279,9 +279,9 @@ Helpful workspace flags:
 
 `apex credits` shows standard, audit, fix review, and Lite scan entitlements when the server returns them.
 
-## Service Keys And The Hosted API
+## Service Keys, Hosted MCP, And The REST API
 
-Use the hosted Apex API for HTTP-only, headless integrations such as serverless functions, cron jobs, and internal audit hubs. Use the CLI or stdio MCP server for local and interactive agent workflows. The full HTTP contract is in the [Apex API documentation](https://ai.cantina.xyz/docs/apex-api).
+Use hosted MCP for production agents that need a normal HTTPS endpoint. Use the REST API for explicit HTTP/JSON integrations such as serverless functions, cron jobs, and internal audit hubs. Use the CLI or local stdio MCP server when an agent needs direct access to a repository checkout or local archive. The complete hosted integration contract is in the [Apex API documentation](https://ai.cantina.xyz/docs/apex-api).
 
 An organization manager can create a service key with an existing Apex device-login session. Service-key commands never start device login implicitly, so run `apex login` first if needed:
 
@@ -309,7 +309,40 @@ apex service-key revoke <key-id>
 
 Service-key management is intentionally available only through the scripted CLI. It is not exposed as an MCP tool or interactive-shell command, which keeps raw secrets out of model tool results and transcripts. The CLI requires an existing device-login bearer session, never initiates login from these commands, and never stores a created service key locally.
 
-`APEX_SERVICE_KEY` authenticates the hosted REST API only; it does not authenticate CLI commands or replace `apex login`. When `apex doctor` finds a service key but no active device-login session, it reports that split before starting a login flow. `APEX_API_KEY` is also recognized for this diagnostic so older integrations receive migration guidance, but `APEX_SERVICE_KEY` is the documented REST variable.
+`APEX_SERVICE_KEY` authenticates hosted MCP and REST requests; it does not authenticate the local CLI or stdio MCP and does not replace `apex login` there. When `apex doctor` finds a service key but no active local device-login session, it reports that split before starting a login flow. `APEX_API_KEY` is also recognized for this diagnostic so older integrations receive migration guidance, but `APEX_SERVICE_KEY` is the documented hosted-integration variable.
+
+### Hosted HTTPS MCP
+
+Point any Streamable HTTP MCP client at `https://ai.cantina.xyz/mcp` and send the service key as `Authorization: Bearer <TOKEN>`. No local `apex-mcp` process, browser, TTY, or device-login session is required.
+
+Keep the key in the environment. For Codex:
+
+```bash
+export APEX_SERVICE_KEY='<service-key>'
+codex mcp add apex \
+  --url https://ai.cantina.xyz/mcp \
+  --bearer-token-env-var APEX_SERVICE_KEY
+```
+
+Claude Code can expand the same environment variable from `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "apex": {
+      "type": "http",
+      "url": "https://ai.cantina.xyz/mcp",
+      "headers": {
+        "Authorization": "Bearer ${APEX_SERVICE_KEY}"
+      }
+    }
+  }
+}
+```
+
+The hosted server exposes `apex-credits`, `apex-workspaces`, `apex-scan`, `apex-status`, `apex-cancel-scan`, `apex-findings`, and `apex-workspace-findings`. It operates only on repositories and workspaces available to the service key's organization. Use local stdio MCP for device auth, local filesystem/archive access, provider connection, setup, comments, feedback, fix reviews, and trial flows.
+
+### Hosted REST API
 
 Use the service key as a bearer token with the hosted scan lifecycle:
 
@@ -337,7 +370,7 @@ curl \
   https://ai.cantina.xyz/api/apex/v1/scans/$SCAN_ID/findings
 ```
 
-For a remote GitHub scan, the repository must already be linked to an active Apex workspace. This remote-repository flow never creates, binds, or mutates workspaces. Apex selects the workspace automatically when exactly one active workspace matches the repository; pass the optional `workspaceId` to disambiguate multiple matches. Zero matches, or multiple matches without a valid `workspaceId`, return HTTP `409`.
+For a remote GitHub scan, the repository must be connected to the service key's Apex organization. Apex reuses an active linked workspace when one exists; if none exists, the request creates and links a workspace named after the canonical repository before the scan starts. Pass `workspaceId` to disambiguate multiple matches. An explicit workspace/repository mismatch returns HTTP `409` instead of silently rewriting that workspace.
 
 For a local or non-Git checkout, use the service API's source-upload flow instead. It can create or reuse a workspace, uploads a `tar.gz` archive, and starts the scan with a `local_archive` source. A newly created local workspace has no threat model to reuse, so its first scan must send `generateThreatModel: true`. See the [Apex service API guide](https://ai.cantina.xyz/docs/apex-api) for the current request schemas and limits.
 
@@ -347,11 +380,11 @@ Every trigger request requires an `Idempotency-Key`. Generate one stable key for
 
 Example prompt for Claude Code:
 
-> Build an Apex adapter for our serverless audit hub using the hosted HTTP API, not the Apex CLI or MCP server. Assume the GitHub repository is already linked to an active Apex workspace; this API must not create or mutate workspaces. Read `APEX_SERVICE_KEY` from the environment, generate one stable `Idempotency-Key` per intended scan, and reuse it with the identical request body only after a transport error, timeout, or `5xx`; after correcting a definitive `4xx`, use a new key. POST the repository URL and exact commit to `/api/apex/v1/scans`, include `workspaceId` when needed to disambiguate matches, and handle a `409` workspace-resolution response. Treat optional `paths` as non-binding focus hints, not a security boundary. Poll `/api/apex/v1/scans/{scanId}` until terminal, then fetch `/api/apex/v1/scans/{scanId}/findings`. Preserve the raw GitLab SAST payload, including drafts, and deduplicate findings by stable ID. Never print or log the service key.
+> Build an Apex adapter for our serverless audit hub using the hosted REST API, not the Apex CLI or local stdio MCP server. Read `APEX_SERVICE_KEY` from the environment, generate one stable `Idempotency-Key` per intended scan, and reuse it with the identical request body only after a transport error, timeout, or `5xx`; after correcting a definitive `4xx`, use a new key. POST the connected GitHub repository URL and exact commit to `/api/apex/v1/scans`, include `workspaceId` when needed to disambiguate matches, and handle a `409` workspace-resolution response. Treat optional `paths` as non-binding focus hints, not a security boundary. Poll `/api/apex/v1/scans/{scanId}` until terminal, then fetch `/api/apex/v1/scans/{scanId}/findings`. Preserve the raw GitLab SAST payload, including drafts, and deduplicate findings by stable ID. Never print or log the service key.
 
 Example prompt for Codex:
 
-> Add Apex to this headless auditor integration using the hosted REST API. Use bearer auth from `APEX_SERVICE_KEY`; do not shell out to `apex` or start MCP. The GitHub repository must already belong to an active Apex workspace, and the adapter must not create or mutate workspaces. Implement scan trigger, `409` workspace-resolution handling, status polling with bounded backoff, terminal failure handling, and findings retrieval. Send `repoUrl`, `commit`, optional `paths`, and optional `workspaceId`; treat `paths` as non-binding focus hints rather than a hard security boundary. Generate a stable `Idempotency-Key` for each intended scan. Preserve it only for an identical transport/timeout/`5xx` retry; after correcting a definitive `4xx`, submit with a new key. Keep the returned `scanId`, and store the unmodified findings payload, including drafts, alongside normalized findings. Add tests with mocked HTTP responses and ensure credentials are redacted from errors and logs.
+> Add Apex to this headless auditor integration using the hosted REST API. Use bearer auth from `APEX_SERVICE_KEY`; do not shell out to `apex` or start a local stdio MCP process. Implement scan trigger, `409` workspace-resolution handling, status polling with bounded backoff, terminal failure handling, and findings retrieval. Send the connected GitHub `repoUrl`, exact `commit`, optional `paths`, and optional `workspaceId`; treat `paths` as non-binding focus hints rather than a hard security boundary. Generate a stable `Idempotency-Key` for each intended scan. Preserve it only for an identical transport/timeout/`5xx` retry; after correcting a definitive `4xx`, submit with a new key. Keep the returned `scanId`, and store the unmodified findings payload, including drafts, alongside normalized findings. Add tests with mocked HTTP responses and ensure credentials are redacted from errors and logs.
 
 For a P1-only integration where scans are started in the Apex UI:
 
@@ -416,7 +449,12 @@ PR scans require exactly one provider-backed GitHub repository. If the current d
 
 ## LLM / MCP Usage
 
-The CLI now ships an MCP server so LLM clients can drive Apex directly over stdio.
+Apex has two MCP transports:
+
+- Hosted Streamable HTTP at `https://ai.cantina.xyz/mcp`, authenticated with an organization service key, for production agents that do not need the caller's filesystem.
+- The `apex-mcp` stdio server shipped by this package, authenticated with device login, for repository-local and interactive agent workflows.
+
+See [Hosted HTTPS MCP](#hosted-https-mcp) for the production URL and Bearer-token configuration. The rest of this section configures the local stdio server.
 
 If Apex is installed globally, prefer:
 
@@ -511,7 +549,7 @@ If you need to launch through `pnpm`, use `--silent`:
 
 Do not point an MCP client at plain `pnpm mcp`. `pnpm` writes its script banner to `stdout` before the protocol stream, which can break the `initialize` handshake.
 
-The MCP server exposes Apex-specific tools for:
+The local stdio MCP server exposes Apex-specific tools for:
 
 - auth status and device login
 - local guest-session deadlines through `apex-trial-status` (never the code or claim token)
@@ -524,7 +562,7 @@ The MCP server exposes Apex-specific tools for:
 - finding comments and valid/invalid feedback with `apex-finding-comment` and `apex-finding-feedback`
 - Fix PR and current-repository fix review scans with `apex-finding-fix-review`, optionally after `apex-finding-feedback`
 
-The MCP server does not expose trial redemption, trial claim, or service-key creation, listing, or revocation. When a user supplies a Cantina trial code, run `apex redeem <code>` in a terminal instead of starting device login or putting the code in an MCP call. For HTTP-only serverless and cron integrations, use the [hosted Apex API](https://ai.cantina.xyz/docs/apex-api) directly instead of launching the stdio MCP server.
+Neither MCP surface exposes trial redemption, trial claim, or service-key creation, listing, or revocation as tools. When a user supplies a Cantina trial code, run `apex redeem <code>` in a terminal instead of starting device login or putting the code in an MCP call. Production MCP clients should connect to `https://ai.cantina.xyz/mcp`; HTTP applications can use the [hosted Apex REST API](https://ai.cantina.xyz/docs/apex-api) directly. Do not launch the local stdio server as an HTTP adapter.
 
 For repository-scoped operations, pass `cwd` explicitly so the server can resolve the right `.apex/workspace.json` binding and repository roots.
 
@@ -586,7 +624,7 @@ Telemetry event posts do not include bearer tokens. The telemetry endpoint is `P
     {
       "schemaVersion": 1,
       "event": "apex.invocation.completed",
-      "cliVersion": "0.1.27",
+      "cliVersion": "0.1.28",
       "invocation": {
         "surface": "mcp",
         "command": "apex-scan",
@@ -617,7 +655,7 @@ The npm package also includes marketplace-ready plugin artifacts:
 - `.claude-plugin/plugin.json` and `.mcp.claude.json` for Claude Code plugin installs
 - `.claude-plugin/marketplace.json` for a Claude marketplace entry backed by the public npm package
 
-These plugin installs launch the pinned npm package with `npx -y -p @cantinasecurity/apex-cli@0.1.27 apex-mcp`, so users do not need to install `apex` globally before enabling the plugin.
+These plugin installs launch the pinned npm package with `npx -y -p @cantinasecurity/apex-cli@0.1.28 apex-mcp`, so users do not need to install `apex` globally before enabling the plugin.
 
 The repository also includes `.agents/plugins/marketplace.json` for local Codex marketplace testing from a checkout.
 

package/dist/help.js

@@ -90,7 +90,7 @@ Tips:
   After a guest scan, run apex claim on the same machine within the displayed claim deadline to keep the results.
   Claim moves trial results into the selected Cantina workspace when you can run scans there, or into your existing personal workspace.
   Service-key commands require an existing login; run apex login first when needed.
-  APEX_SERVICE_KEY authenticates the hosted REST API only; it does not replace apex login for CLI commands.
+  APEX_SERVICE_KEY authenticates https://ai.cantina.xyz/mcp and hosted REST; it does not replace apex login for local CLI or stdio MCP commands.
   Apex automatically selects your company when only one is available. With multiple companies, choose one interactively or pass --company.
   Service-key creation also requires --name and reveals the secret only once; omit --scope to grant all hosted API scopes.
   Service-key management is available only in the scripted CLI, not the interactive shell or MCP server.

package/dist/mcp.js

@@ -28,8 +28,8 @@ Notes:
 - Pass cwd explicitly for repository-specific operations.
 - Tool calls are always non-interactive and never auto-open a browser.
 - Finding write tools use the same Apex device-login credentials as read tools. Never ask for browser cookies or CANTINA_AUTH_TOKEN. An error requiring CANTINA_AUTH_TOKEN proves the MCP server is outdated; update Apex CLI, re-run apex setup for this client, restart it, and retry.
-- Organization service-key creation, listing, and revocation are intentionally scripted-CLI-only and are not exposed as MCP tools. Never ask a user to paste a service key into an MCP prompt or tool call.
-- HTTP-only serverless and cron integrations should use the hosted API documented at https://ai.cantina.xyz/docs/apex-api instead of launching this stdio server.
+- Organization service-key creation, listing, and revocation are intentionally scripted-CLI-only and are not exposed as MCP tools. Never ask a user to paste a service key into a prompt or tool argument. A hosted MCP client supplies it only as the HTTP Authorization header.
+- Production agents that do not need local filesystem access can connect to https://ai.cantina.xyz/mcp over Streamable HTTP with Authorization: Bearer <service-key>. Serverless and cron applications can instead use the REST API documented at https://ai.cantina.xyz/docs/apex-api. This local stdio server continues to use device login.
 - Use mode "audit" for audit scans; "ultra" remains accepted as a legacy alias. Use mode "lite" only for beta-enabled provider-backed Lite scans, and mode "pr" for GitHub pull request scans.
 - Starting a PR scan may run alongside active workspace scans and does not require force. Starting any non-PR scan still treats every active scan, including a PR scan, as a blocker; use force only when the user explicitly wants that overlap.
 - Doctor is read-only for guest sessions and reports the local snapshot plan without reserving a workspace.

package/dist/service-key-environment.js

@@ -14,9 +14,9 @@ export function getServiceKeyCliAuthGuidance(env = process.env) {
         return null;
     }
     const legacyVariableGuidance = variableName === "APEX_API_KEY"
-        ? " For REST API examples, rename APEX_API_KEY to APEX_SERVICE_KEY."
+        ? " For hosted MCP and REST examples, rename APEX_API_KEY to APEX_SERVICE_KEY."
         : "";
-    return (`Apex service key detected in ${variableName}, but service keys authenticate the hosted REST API, not the Apex CLI. ` +
-        "Use `apex login` for CLI device authentication, or use the REST API for a headless/service-account integration: https://ai.cantina.xyz/docs/apex-api." +
+    return (`Apex service key detected in ${variableName}, but service keys authenticate the hosted MCP and REST endpoints, not the local Apex CLI. ` +
+        "Use `apex login` for local CLI device authentication, or use https://ai.cantina.xyz/mcp or the REST API for a headless/service-account integration: https://ai.cantina.xyz/docs/apex-api." +
         legacyVariableGuidance);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cantinasecurity/apex-cli",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Standalone CLI and MCP server for Apex.",
   "private": false,
   "type": "module",

package/skills/apex-cli/SKILL.md

@@ -7,9 +7,11 @@ description: Use when a user wants to start Apex scans, inspect findings, bind w
 
 This skill is bundled with Apex CLI and can be installed into Codex with `apex setup codex` or GitHub Copilot CLI with `apex setup copilot`.
 
-Prefer the Apex MCP tools over running `apex` in the shell when the server is available.
+Prefer the Apex MCP tools over running `apex` in the shell when the server is available. The tools installed by `apex setup` use the local stdio server and device login.
 
-For serverless, cron, or other HTTP-only integrations, use the hosted Apex REST API instead of CLI or stdio MCP. Its scan trigger, status, and findings contract is documented at https://ai.cantina.xyz/docs/apex-api.
+For a production MCP client that does not need local filesystem access, use the hosted Streamable HTTP endpoint at `https://ai.cantina.xyz/mcp`. Read the organization service key from `APEX_SERVICE_KEY` and supply it only as `Authorization: Bearer <TOKEN>`; never put the raw key in a tool argument, result, prompt, source file, or log. The hosted tools are `apex-credits`, `apex-workspaces`, `apex-scan`, `apex-status`, `apex-cancel-scan`, `apex-findings`, and `apex-workspace-findings`.
+
+For serverless, cron, or other explicit HTTP/JSON integrations, use the hosted Apex REST API instead of CLI or local stdio MCP. The hosted MCP and REST contract is documented at https://ai.cantina.xyz/docs/apex-api.
 
 `apex setup codex` configures the MCP server with client attribution so Apex can distinguish Codex MCP usage from direct CLI usage. Users can inspect or disable anonymous local usage telemetry with `apex telemetry status` and `apex telemetry disable`.
 
@@ -60,11 +62,12 @@ Guidelines:
 - Do not rely on interactive CLI prompts. The MCP tools are intentionally non-interactive.
 - The MCP-only `apex-trial-status` tool may report local guest and claim deadlines, but it must never return a trial code or claim token. `claimAvailable` becomes false at a known passed deadline; missing or invalid local deadline metadata remains conservative and server-authoritative. There is intentionally no MCP redemption or claim tool.
 - When MCP remains available after a guest scan, remind the user to run `apex claim` on the same machine while `claimAvailable` is true; after a known passed deadline, continue with normal account login.
-- Service-key management has no MCP tools. Never ask a user to paste a service key into a prompt, and never place one in an MCP call, tool result, source file, or log.
+- Service-key creation, listing, and revocation have no MCP tools. Never ask a user to paste a service key into a prompt, and never place one in a tool argument, tool result, source file, or log. Hosted MCP clients may read it from a secret-backed environment variable for the HTTP Authorization header.
 - If a user explicitly needs a new service key, tell them to run `apex login` if needed, then run `apex service-key create --name <name> --scope <scope[,scope]>` directly in their own terminal. Use only the required scopes: `scans:create` to query credit availability or trigger, `scans:read` to poll status, and `findings:read` to retrieve findings. A P1-only adapter can use `--scope scans:read,findings:read`; omitting `--scope` grants all three. The CLI automatically selects the company when only one is available and prompts when there are several; use `--company <id-or-handle>` to skip that prompt or resolve a non-interactive command. Service-key commands never initiate login, and the secret is shown once.
-- For a headless HTTP adapter, read the service key from the secret-backed `APEX_SERVICE_KEY` environment variable, send it as a bearer token to `/api/apex/v1`, and redact it from errors and logs. A service key does not authenticate CLI or MCP commands; those use device login. Do not shell out to `apex` or launch MCP from the adapter.
+- For a hosted MCP client, connect to `https://ai.cantina.xyz/mcp` and send `APEX_SERVICE_KEY` as a Bearer header. The service key authenticates hosted MCP, but not the local CLI or stdio MCP; those use device login.
+- For a headless REST adapter, read the service key from the secret-backed `APEX_SERVICE_KEY` environment variable, send it as a bearer token to `/api/apex/v1`, and redact it from errors and logs. Do not shell out to `apex` or launch local MCP from the adapter.
 - Hosted API integrations can call `GET /api/apex/v1/credits` with `scans:create` scope to inspect the organization's current standard, audit, and Lite balances and effective scan-type availability. Treat the response as a point-in-time snapshot; scan creation remains authoritative.
-- Hosted API v1 remote-repository scans require the GitHub repository to be linked to an active Apex workspace and do not create or mutate workspaces; use optional `workspaceId` to disambiguate matches and treat zero or ambiguous matches as HTTP `409` setup errors. Local or non-Git scans use the documented source-upload flow, which can create or reuse a workspace; send `generateThreatModel: true` for the first scan of a newly created local workspace.
+- Hosted remote-repository scans require the GitHub repository to be connected to the service key's Apex organization. They reuse a linked active workspace or create and link one when no match exists; use optional `workspaceId` to disambiguate multiple matches and treat explicit workspace/repository mismatches as HTTP `409` setup errors. Local or non-Git REST scans use the documented source-upload flow; send `generateThreatModel: true` for the first scan of a newly created local workspace.
 - Hosted scan triggers require `Idempotency-Key`. Reuse one stable key only for an identical transport/timeout/5xx retry. After correcting a definitive 4xx response, or for any new intended scan, use a new key.
 - `apex-credits` reports standard credits plus audit, fix review, and Lite scan entitlements when Bedrock returns those balances.
 - `apex-scan` scans the provided `cwd` by default; pass `repoPaths` only when the user asks to scan explicit alternate roots.
@@ -92,3 +95,7 @@ in a terminal, use MCP for scan/status/findings after redemption, then check the
 MCP-only `apex-trial-status` tool and remind the user to run `apex claim`
 locally while `claimAvailable` remains true. In a CLI-only flow, use the
 redeem response's `claimDeadline` instead.
+
+Example hosted MCP flow: configure `https://ai.cantina.xyz/mcp` as a
+Streamable HTTP server, source its Bearer token from `APEX_SERVICE_KEY`, and
+verify `apex-credits` without printing the credential.