# Connect your agent to Cantina Apex Canonical guide: https://ai.cantina.xyz/docs/agents.md Human-readable guide: https://ai.cantina.xyz/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. ## 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.28 ``` 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. ## 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://ai.cantina.xyz/docs/apex-api for setup and supported tools. This is a separate integration with different tool inputs and an organization-scoped service key supplied as an Authorization Bearer header. Use environment variables or the client's secret storage, never a token pasted into chat. A manager or administrator creates the key; use read-only scopes for reading results. Verify with a read-only call. Do not send local `cwd` or local workspace-binding tool inputs to the hosted server. ## 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.