# Connect your agent to Cantina Apex Canonical guide: https://apex.cantina.security/docs/agents.md Human-readable guide: https://apex.cantina.security/docs/agents Apex brings security scans and findings into a coding agent. Connect an existing account and workspace first; setup alone does not authorize a new scan, finding feedback, or a Fix Review. ## What the user will do 1. Open your repository in your agent: Use a coding agent with terminal access, such as Claude Code, Codex, Cursor, or GitHub Copilot CLI. Copy the prompt above into its chat. 2. Sign in and reload the agent: Your agent installs Apex and sets up its tools. Complete the Cantina sign-in link in your browser when prompted. Restart the agent or open a new chat if it needs to load the new tools, then paste the same prompt again. 3. See your existing scan results: The agent checks the connection, selects the workspace for your repository, and reads your latest scan. If more than one workspace matches, it asks you to choose. 4. Manage your CLI sessions: Select the agent button (>_) in the Apex header to check your connection or sign out of the CLI on every device. Sign-in codes you have already approved also expire if they have not been redeemed. Run apex login to connect again. Guest trials and remote MCP connections are managed separately. ## 1. Install and connect the local MCP server Use local MCP for coding agents with terminal access to the user's repository. It uses Apex device login. Check Node.js 20+ and the installed Apex version first; if Apex is missing or outdated, install the documented package: ```sh npm install -g @cantinasecurity/apex-cli@0.1.45 ``` Identify the agent running this prompt before changing its configuration. Use its setup command below; do not configure unrelated clients. - Claude Code: `apex setup claude`. Requires the Claude Code CLI. Run from your repository to install its project skill as well as the MCP server. - Codex: `apex setup codex`. Requires the Codex CLI on PATH. Restart Codex after setup so it can load the Apex MCP server and skill. - Copilot CLI: `apex setup copilot`. Requires GitHub Copilot CLI. Restart it after setup so the Apex tools are available. Cursor: merge this entry into the repository's `.cursor/mcp.json`, preserving existing servers. Do not run `apex setup cursor`; it is not a supported setup target. Other local MCP clients can use the same stdio command in their own configuration format: ```json { "mcpServers": { "apex": { "type": "stdio", "command": "apex-mcp", "args": [] } } } ``` The MCP command is `apex-mcp` with no arguments. If the client cannot resolve it on PATH, use the absolute executable path returned by the installation. Keep existing configuration and credentials intact. Never place tokens in the repository or chat. After registration, ask the user to restart their agent or open a new chat if the Apex tools are not available in the current session. Give them the original prompt to resume. Do not claim the connection is verified until a real Apex tool succeeds. ## 2. Sign in without exposing credentials 1. Call `apex-auth-status` and `apex-trial-status` to check for existing account or guest access. 2. If an unexpired trial claim is available, use `apex claim` in a terminal on the same machine and user home that ran the trial. Preserve the existing guest session. If the user supplied a trial code, follow https://ai.cantina.xyz/skills/onboarding.md instead of starting a new device login; trial redemption is terminal-only. 3. When no usable session or claim exists, call `apex-auth-start`. Show the returned verification URL and user code so the user can finish sign-in in their own browser. Call `apex-auth-wait` with the returned device code and any other fields required by the installed tool schema. Handle pending or expired login explicitly. 4. Alternatively, the user can run `apex login` in their own terminal and then resume the agent. Local MCP uses the same Apex login for reading findings, commenting, feedback, and Fix Review. Never ask for browser cookies, passwords, or `CANTINA_AUTH_TOKEN`. If a tool asks for a separate browser token, update Apex CLI, re-run the client's setup, and restart it. Service keys do not authenticate the local CLI or stdio MCP server. An Apex account suspension returns HTTP 403 for browser, CLI, service-key, and hosted MCP access, including token refresh and approved device login. Stop account operations and contact support; signing in again or issuing another credential does not restore access. An account-access verification outage returns HTTP 503 and can be retried later. ## 3. Reuse the existing workspace and scan Pass the absolute repository path as `cwd` for repository-specific tools. Respect an explicit workspace or scan supplied by the user. 1. Call `apex-workspace` with `cwd` to read the current local binding. Do not start a scan to repair a missing binding. Do not call `apex-doctor` during connection setup: for an account without a binding, its source-resolution step can create a workspace. 2. If no workspace is bound, or the binding does not match the requested workspace, call `apex-workspaces`. Use the matching company and repository to identify the workspace. If several match, ask the user to choose; never guess across companies. 3. Call `apex-workspace-use` with `cwd` and `workspaceRef` (the existing workspace's name, prefix, or ID) to bind this directory. Pass `company` explicitly when needed. This changes the local binding, not the remote scan. 4. Call `apex-scans` to list the workspace's scans. For a user who already ran a scan, select their requested scan or the latest completed scan. If a scan is still running, report its status and URL; do not launch a replacement. 5. Call `apex-findings` with the selected public Bedrock scan ID using the installed tool's scan selector. Use `apex-workspace-findings` with `findingState: "open"` for open findings across scans. Follow pagination or report any result limit so a partial list is not presented as complete. 6. Report the connected agent, workspace, scan ID/status/URL when returned, and a short findings summary with IDs and affected files. If there are no completed scans or no findings, say so. ## 4. Continue only with the requested workflow ### Review my first scan Connect to the existing workspace for this repository and list its scans. Read the latest completed scan and summarize its critical and high findings, with finding IDs, affected files, and suggested next steps. If several workspaces match, ask which one. Do not start a scan or change findings. ### Run a scan Check authentication, workspace binding, source scope, available credits, and active scans. Propose one standard scan, show the scope and credit use, and ask before starting. Once accepted, return the scan ID and URL without starting another scan or continuously polling. ### Prepare a fix Read https://ai.cantina.xyz/docs/fix-review. List the open findings in the existing workspace and help the user choose one to fix. Inspect the finding and affected code, implement the fix on a branch, and run relevant tests. Show the diff and test results before publishing a PR, changing Apex feedback, or starting a Fix Review. Before an authorized new scan, check `apex-credits`, repository scope, and active scans. Use `apex-doctor` for source planning after binding the selected existing workspace. If a new workspace is needed, explain that first and obtain the user's confirmation before provisioning it. Start one scan with the requested mode and return the accepted scan ID and URL. Do not continuously poll. Use `force` only for an explicitly requested overlap with an active scan. A standard scan can use a local snapshot; audit and Lite need connected GitHub or GitLab sources, and local CLI PR scans need a connected GitHub repository. Check the scan manual for mode requirements and entitlements. Reading a finding is not authorization to change feedback, publish code, or start a Fix Review. When those actions are requested, follow the Fix Review guide and the actual tool schemas; include relevant test evidence and the correct finding and scan IDs. ## Hosted or headless agents Agents running without a local terminal can use hosted Streamable HTTP MCP at https://ai.cantina.xyz/mcp or the REST API. Read https://apex.cantina.security/docs/apex-api for setup and supported tools. These integrations use different tool inputs from local MCP. ChatGPT and supported Codex loopback clients can connect to hosted MCP through organization-manager OAuth consent. Organization-scoped service keys remain available for hosted MCP and are required for REST clients; supply a service key as an Authorization Bearer header. A manager or administrator creates the key; store it in environment variables or the client's secret storage, never paste a token into chat. Use read-only scopes for reading results and verify with a read-only call. Do not send local `cwd` or local workspace-binding tool inputs to the hosted server. For Codex OAuth setup, run `codex mcp add apex --url https://ai.cantina.xyz/mcp`, then `codex mcp login apex` and complete the browser consent flow. Do not configure a bearer-token environment variable for that OAuth entry. Alternatively, configure an existing service key with `codex mcp add apex --url https://ai.cantina.xyz/mcp --bearer-token-env-var APEX_SERVICE_KEY`. Choose one authentication method for the server entry; connecting alone does not authorize or start a scan. ### Apex Black web security scans The Apex Black plugin uses browser OAuth account linking by default in both ChatGPT and Codex: an organization manager or eligible researcher signs into Apex, selects an organization or their owned personal workspace, and consents to scan and finding access. The server supports dynamic public-client registration with S256 PKCE; no service key or environment setup is required. OAuth connections expire after 30 days and can be revoked through the organization Settings service-key entry named `MCP OAuth: `. Existing service keys remain supported for unattended integrations. Both connections enforce the same company scope, credits, and launch idempotency. The OAuth migration and hosted server change must be deployed before connecting. Capture the requested targets and exclusions before sign-in and retain the pending request, any existing consent, and one unique idempotency key through setup. Use the host's Connect/Authenticate action. With Codex terminal access, discover the existing hosted entry at https://ai.cantina.xyz/mcp using `codex mcp list --json`, then run `codex mcp login --scopes scans:create,scans:read,findings:read` and let the user complete browser consent. Refresh tool discovery and continue the same request. If the host cannot refresh tools in the conversation, preserve the request and explain that specific limitation rather than making the user repeat it. Distinguish network or Cloudflare blocks from missing authentication; service-key setup cannot repair an edge block. Existing Apex customers can use hosted `apex-black-start` when successful authenticated discovery advertises that tool and Apex Black beta is enabled for their organization or individually for the researcher who issued the credential for their owned personal workspace. Researchers do not need to create or join a company. Ordinary organization credentials do not inherit their creator's individual beta grant. Installing the plugin alone does not enable the tool or beta. The connection needs `scans:create`; `scans:read` and `findings:read` allow progress checks and result retrieval. A new Black scan costs 200 Standard credits. Call `apex-black-prepare` with the exact `targetUrls` first to check Black access, scanning availability, and credits without creating a workspace or reserving credits. Its `canStart` and `blockers` describe readiness, with support or billing actions for missing prerequisites. Show the returned action, keep the request, and recheck after setup. Older deployments can use `apex-credits`, requiring scanning to be enabled and at least 200 Standard credits; that response does not verify Black access. Launch rechecks current entitlement and available credits. After preparation, ensure the user's authorization for active security testing of every target and acceptance of the credit cost are present. Ask once for any missing consent in a concise question naming the exact origins and 200-credit cost. Honor authorization already provided in the session without asking again. Pass `targetUrls` as 1-16 exact HTTPS origins, without credentials, paths, query strings, or fragments. Unlisted origins are outside scope. Optional `scopeText` (maximum 100,000 characters) supplies testing instructions and exclusions, `threatModelContext` (maximum 4,000 characters) supplies application context, and `workspaceName` (maximum 242 characters, leaving room for the Apex Black prefix) names the created workspace. Set `authorizationAccepted: true` only when this authorization is present; connection or setup alone does not authorize testing. Use one stable `idempotencyKey` for the intended scan. Keep the connected company's ID from preparation or credits as `expectedCompanyId`. When the discovered start schema advertises this field, pass it to every start and replay. OAuth starts require it, and a mismatch rejects the operation before any workspace or credit reservation. If an older schema omits the field, retain the ID locally and omit that unsupported argument. Never replace the original ID after reconnecting; verify the same organization before starting or replaying and stop if it differs. Keep the returned `scanId`, `workspaceId`, `statusUrl`, and `findingsUrl`. Report the accepted scan and use `apex-status` with `scanId` for requested progress checks, then `apex-findings` after completion. Do not launch another scan to check status. After a transport failure or retryable error, reconcile or replay the submitted operation before new-launch preparation: reuse the same key and identical input and respect `retryAfterSeconds`. An identical retry returns the same scan without another charge and needs no new 200-credit balance. After reconnection, verify the original company with `apex-credits` without gating replay on its balance; reconnect to the original organization if the company differs. Changed input with the same key returns 409. Any stored remote-start failure, including `APEX_BLACK_START_FAILED`, is replayed without relaunching; keep durable request and workspace IDs and contact support before attempting another request. Do not switch to a new key to bypass a stored start failure. For customer-facing confirmations, keep IDs and tool JSON internal. Name the website, give the actual status and credit cost, and link **View your scan** to the returned `scanUrl`. This absolute URL opens the authenticated Apex scan page; `statusUrl` and `findingsUrl` are API endpoints. Retain the IDs for subsequent "my scan" requests. Suggest "Check my scan's progress" while running and "Summarize the findings" or "What should I fix first?" after completion. Do not promise an automatic notification unless one is actually configured. REST clients use `POST /api/apex/v1/apex-black/scans` with the same body excluding the MCP-only `expectedCompanyId` and `idempotencyKey`; supply the latter in the `Idempotency-Key` header. The 202 response includes the durable IDs and URLs, status, the current reserved `creditCost` (200 for a new scan), `scanType: "standard"`, and `operationType: "apex_black"`. The scan type matches the shared inventory and credit ledger; the operation type identifies the web scan. An identical start retry reports the persisted status and current reserved cost without restarting, including a zero cost after cancellation wins before launch. Use the existing scan status and findings endpoints. The complete contract is at https://ai.cantina.xyz/api/apex/v1/openapi.json. ## More documentation When the user's prompt names a guide or workflow, read its linked page and follow the task below. A request for setup or planning does not start a scan automatically. ### Docs Read https://ai.cantina.xyz/docs. Help me choose the right Apex workflow for this repository. ### Onboarding Read https://ai.cantina.xyz/docs/onboarding. Help me connect this repository to Apex and prepare my workspace and security context. Reuse an existing workspace if one matches; ask before creating one or starting a scan. ### Workspaces Read https://ai.cantina.xyz/docs/workspaces. Help me inspect this repository's existing Apex workspace and explain its scope. Ask before changing scope, archiving, or restoring a workspace. ### Scan manual Read https://ai.cantina.xyz/docs/manual. Inspect this repository and recommend an Apex scan plan, including scope, threat model, scan mode, and any useful split between systems. Show the plan before starting a scan. ### Fix Review Read https://ai.cantina.xyz/docs/fix-review. Help me select an existing Apex finding and review its proposed fix. Explain the evidence and the Fix Review workflow. Ask before publishing a PR, changing feedback, or starting a Fix Review. ### Scheduled scans Read https://ai.cantina.xyz/docs/scheduled-scans. Help me choose an Apex scan or Fix Review schedule for my workspace. Explain the cadence and prerequisites and guide me through the documented app settings; ask before enabling or changing a schedule. Do not invent CLI or MCP scheduling commands. ### CLI Read https://ai.cantina.xyz/docs/apex-cli. Set up Apex CLI and its MCP integration for my coding agent. Reuse this repository's existing workspace and verify the connection by reading scan status. Do not start a scan. ### API Read https://ai.cantina.xyz/docs/apex-api. Help me connect a headless agent to Apex using hosted MCP or REST. Choose the documented integration and least-privilege scopes, keep credentials in environment variables, and verify with a read-only request. Never ask me to paste a secret into chat or start a scan during setup.