Integrations

BoringSec MCP for Claude Code, Codex, and Cursor

A full local security assistant for Claude Code, Codex, and Cursor: quality checks, security findings, remediation prompts, AI-ready rules, compliance reports, and transparent usage visibility.

How it works

The MCP package authenticates like Claude Code style device login: you run one login command, approve a short authorization code on boringsec.com, and we mint a dedicated machine credential behind the scenes. No manual secret copy is required for normal setup.

On supported systems the credential is stored in the OS keychain or secret service. The package only falls back to the local config file when no secure store is available.

That machine credential still uses the same BoringSec API, scopes, tier gates, usage accounting, and billing rules as the rest of the platform, so the behavior is consistent and auditable.

Privacy boundaries

Privacy is split explicitly into three boundaries: local_only, hosted_sanitized, and metadata_only. Hosted project analysis can send sanitized code/config when you explicitly invoke project review or other hosted tools; stats telemetry stores only privacy-safe counts and hashed workspace identity.

Setup

Step 1: Authenticate once

terminal

npx -y @boringsec/claude-code login

This opens a one-time authorization flow at /auth/device.

Step 2: Bootstrap Claude Code and Cursor automatically

terminal

npx -y @boringsec/claude-code init --editor both --scope project --write-rules

This writes .mcp.json, .cursor/mcp.json, .boringsecignore, .boringsec/policy-bundle.json, and starter AGENTS.md plus .cursorrules.

Step 3: Claude Code project config

json

{
  "mcpServers": {
    "boringsec": {
      "command": "npx",
      "args": ["-y", "@boringsec/claude-code"]
    }
  }
}

You normally do not have to write this by hand because init generates it for you.

Step 4: Codex manual setup

The public npm latest tag currently resolves to 0.4.5. That package can run as a Codex MCP server, but its init command only configures Claude Code and Cursor; it does not write .codex/config.toml. Until 0.4.6 is published under latest, add the TOML block below manually and preserve the rest of your existing config.

toml

[mcp_servers.boringsec]
command = "npx"
args = ["-y", "@boringsec/claude-code"]
startup_timeout_sec = 60
tool_timeout_sec = 660

Put this block in the project's .codex/config.toml. Open the repository in Codex and accept the workspace trust prompt before checking the project-scoped server; an untrusted project config is intentionally ignored. For a user-scoped setup, put the same block in $CODEX_HOME/config.toml when CODEX_HOME is set, otherwise use ~/.codex/config.toml.

terminal

codex mcp get boringsec

Run the verification command from the configured project. Local tools are confined to the directory where the MCP server starts; a tool-supplied rootPath cannot read or write outside that workspace.

Local 0.4.6 release candidate only

Contributors testing this repository can build the local package and use its Codex initializer with the commands below. This is not the public npm installation path.

terminal

npm --prefix packages/claude-code run build
node packages/claude-code/dist/server.js init --editor codex --scope project --write-rules --local-build

Step 5: Restart your client

Start a new Codex session or restart Claude Code or Cursor so it reloads the MCP configuration, then ask it to scan your app, repo, or project files.

Step 6: Open your MCP cockpit

The dashboard /mcp-stats page now shows active devices, workspace health, recent MCP runs, privacy boundaries, prompt shortcuts, and the most important next actions.

CLI commands

terminal

npx -y @boringsec/claude-code login
npx -y @boringsec/claude-code doctor
npx -y @boringsec/claude-code doctor --fix
npx -y @boringsec/claude-code init --editor both --scope project --write-rules
# Codex: add the TOML block shown below, then verify it
codex mcp get boringsec
npx -y @boringsec/claude-code review-diff --mode diff --markdown-output boringsec-review.md --sarif-output boringsec-review.sarif --github-annotations-output boringsec-review.annotations.json
npx -y @boringsec/claude-code autofix --issue-code missing-gitignore
npx -y @boringsec/claude-code rotate
npx -y @boringsec/claude-code status
npx -y @boringsec/claude-code logout
npx -y @boringsec/claude-code logout --revoke
npx -y @boringsec/claude-code serve

logout --revoke removes the local credential and revokes the device-issued API key remotely.

doctor --fix bootstraps missing local config and starter rule files.

review-diff generates a local merge gate plus Markdown and SARIF artifacts for CI. autofix prints safe patch blueprints for supported findings, and rotate renews a stored device credential in place.

When a repo links itself to a managed team policy, doctor also checks editor allowlists and device rotation posture against that central policy.

Available tools

boringsec_scan

Scan a deployed URL

boringsec_scan_repo

Scan a public GitHub repository

boringsec_scan_async

Start an asynchronous URL scan for larger workflows

boringsec_workspace_review

Primary editor-facing project review with compact inputs and a readable summary

boringsec_check

Fetch a completed scan by ID

boringsec_scan_status

Poll an asynchronous scan until it finishes

boringsec_ai_analysis

Generate AI risk summary, threat scenarios, and prioritized fixes

boringsec_compliance

Generate PCI DSS, GDPR, SOC 2, HIPAA, or ISO 27001 report

boringsec_fix

Load built-in and community remediation prompts

boringsec_autofix

Generate a safe patch blueprint for supported low-risk findings

boringsec_generate_rules

Generate .cursorrules and/or AGENTS.md

boringsec_policy_packs

List secure coding policy packs and recommended bundles for your stack

boringsec_workspace_rules

Generate or write workspace-managed rule files from .boringsec/policy-bundle.json

boringsec_review_diff

Review the current diff or staged changes with a merge gate, Markdown summary, SARIF, and GitHub annotations

boringsec_sync_waivers

Submit local review waivers into the central org approval queue

boringsec_finding_feedback

Send false-positive, accepted-risk, or resolution feedback back to BoringSec

boringsec_usage

Show quota, features, and usage-based pricing

boringsec_privacy_report

Explain exactly which data stays local or is sent for each tool

boringsec_suggest

Recommend the best next security action for the current workflow

boringsec_stats

Show local project history and privacy-safe account statistics

boringsec_cicd_setup

Generate create-only GitHub Actions or GitLab CI templates without overwriting existing files

Advanced raw tools

Low-level tools like boringsec_scan_workspace, boringsec_scan_project, and boringsec_scan_code are intentionally hidden from the default editor surface so Claude Code and Cursor do not show giant raw payload previews. Power users can re-enable them with BORINGSEC_EXPOSE_ADVANCED_TOOLS=1 for CI or precision debugging.

Recommended workflows

Local repo review

Ask Claude to run boringsec_workspace_review in the current repo before major refactors or releases. It supports auto, staged, diff, and full file selection, and respects .boringsecignore. If you need lower-level controls like diffBaseRef or maxFiles, expose the advanced raw tool surface explicitly.

Long-running scans

Use boringsec_scan_async for Business/Enterprise workflows, then poll with boringsec_scan_status.

AI safety rails

Use boringsec_policy_packs to inspect recommended policy bundles for your stack, then generate or write AGENTS.md and .cursorrules with boringsec_workspace_rules. If your team manages central policy, add managedTeamSlug to .boringsec/policy-bundle.json so local rules and diff review inherit the team baseline. Current packs include baseline rules plus more focused guidance for auth/session hardening, SSRF, webhooks, and payment entitlements. You can also merge live scan findings with boringsec_generate_rules.

Waiver governance and feedback loops

Local .boringsec/review-waivers.json files still work for repo-level suppressions, but managed repos can now push those waivers into the org approval queue with boringsec_sync_waivers. When a finding is noise, accepted risk, or already resolved, send that signal back with boringsec_finding_feedback so the platform keeps a transparent false-positive loop.

Prompt and resource helpers

The MCP server also exposes prompt helpers like boringsec_workspace_review and boringsec_pre_merge_review, plus resources like boringsec://docs/quickstart, boringsec://status/project, boringsec://reports/latest, and boringsec://next-best-actions for richer editor workflows.

PR and CI gates

Use npx -y @boringsec/claude-code review-diff in CI to produce merge-blocking output, Markdown summaries, SARIF uploads, and GitHub workflow annotations. Local .boringsec/review-waivers.json suppressions are honored, and expired waivers surface again as findings. Governance fields like owner, approval, ticket, and expiry are checked by doctor, and repos linked to a managed team policy are also validated against central waiver rules. Supported repo-hardening findings can also be handed to boringsec_autofix for safe patch blueprints before the final manual review. The npm package includes a starter workflow template under templates/github-actions/boringsec-review.yml, and the publish pipeline now runs post-publish registry smoke before the release is considered clean.

Billing and transparency

The MCP package does not create a separate billing universe. It uses the same workspace plan, feature flags, rate limits, quota counters, and usage-based overage rules as the web app and REST API.

If your workspace supports usage-based billing beyond included limits, boringsec_usage shows current quota and the live overage price table returned by the API.

Environment variables

Variable	Required	Purpose
`BORINGSEC_API_KEY`	Optional	Manual override for CI or advanced headless setups
`BORINGSEC_API_URL`	Optional	Custom BoringSec API origin for self-hosted or staging environments

Troubleshooting

Tools are not working?

Run npx -y @boringsec/claude-code doctor. If local config is missing, try npx -y @boringsec/claude-code doctor --fix. If you are not authenticated, run npx -y @boringsec/claude-code login again.

Getting permission or tier errors?

Your workspace plan or granted scopes do not include that capability yet. Approval flow only grants scopes supported by the current tier.

Need raw API keys instead?

You can still create manual API keys from the dashboard, but local editors should generally use device authorization for better security and rotation hygiene.

Device key expiring?

Run npx -y @boringsec/claude-code rotate on that machine to renew the credential without manual secret handling.