arko-mcp

arko-mcp

ARKO's security control engine as a Model Context Protocol (MCP) server — so Claude Code, Cursor, and any MCP-compatible AI coding agent can scan code, validate fixes, and read findings/score/policy directly in their loop.

It is a thin client over the live ARKO API (https://arko.devsecai.io). No scanning logic lives here: every tool call is an authenticated request to the existing plugin / control-plane API, so the 5-layer decision engine, tenant isolation, and the audit trail are all inherited unchanged.

Enterprise model in one line

A developer signs in once with their work email. The backend resolves their enterprise tenant from the email domain (e.g. @forterro.com → Forterro), so every scan that developer's agent runs is tagged to that tenant and shows up in the organisation's Control Plane — same findings, same audit trail as the IDE plugin. Non-enterprise domains fall back to the free tier. Same binary, no per-user config.

write code → arko_scan_code → fix the finding → arko_validate_fix → done
                     ↓ every call authenticated as the real user
        results land in that enterprise's Control Plane (app.arko.devsecai.io)

Authentication — automatic on first use

No separate login step. The first time the agent runs an ARKO tool, the server opens your browser to sign in (Cognito Hosted UI, Authorization Code + PKCE — no secret). After that the refresh token is cached in ~/.arko/credentials.json (0600) and silently refreshed, so it never asks again.

Sign in with your work email → the backend resolves your enterprise tenant from the domain → results appear in that organisation's Control Plane. The agent is the only UI; findings show up in the existing Control Plane.

Optional commands:

arko-mcp login --email you@company.com   # sign in ahead of time (skips the first-use prompt)
arko-mcp whoami                          # identity, tier, enterprise tenant
arko-mcp logout                          # clear cached credentials

Headless / CI: set ARKO_TOKEN=<jwt> (and optionally ARKO_NO_AUTO_LOGIN=1) to skip the browser entirely.

One-time activation by DevSecAI: register the loopback redirect http://localhost:8765/callback on the Cognito app client — see ENTERPRISE-SETUP.md.

Tools

Tool	Endpoint	Use
arko_scan_code	POST /analyze	Scan code you just wrote/changed (SAST, 5-layer engine).
arko_validate_fix	POST /vulnerabilities/check-remediation	Confirm a fix actually closed the finding.
arko_fix_all	POST /analyze → plan	Scan + a prioritised plan to remediate every finding; "make this secure" in one call, then validate.
arko_scan_project	POST /scan/build (+ poll)	Dependency / SCA scan of package manifests (CVEs).
arko_list_findings	GET /org/vulnerabilities	List open findings for the org/tenant.
arko_get_score	GET /score/canonical	Canonical "Hackable" score / posture.
arko_get_policy	GET /org/policies	Active policies + framework coverage (PCI, SOC 2, OWASP…).

The control-plane tools (list_findings, get_score, get_policy) require the user to have an arko-tenant-users row (admin | viewer) — i.e. an enterprise tenant. Scan tools work for any signed-in user.

Install & build (local, pre-publish)

cd packages/mcp
npm install
npm run build      # tsc → dist/
npm run smoke      # MCP handshake + assert all six tools register
npm run authtest   # PKCE / authorize-URL / loopback / credential checks (no live Cognito)

Install in Claude Code — one line

claude mcp add arko -- npx -y arko-mcp

That's the whole install. The first time you ask the agent to scan something, your browser opens to sign in; every time after is automatic.

Local build (pre-publish): claude mcp add arko -- node /ABS/PATH/packages/mcp/dist/index.js

Team distribution — commit a project-scope .mcp.json (see examples/.mcp.json); every developer who opens the repo in Claude Code inherits ARKO, and the first scan signs them in with their work email — their findings route to the org's Control Plane:

{
  "mcpServers": {
    "arko": {
      "command": "npx",
      "args": ["-y", "arko-mcp"],
      "env": { "ARKO_API_BASE_URL": "https://arko.devsecai.io" }
    }
  }
}

No token in the config — auth is the per-developer arko-mcp login.

Other clients (same binary)

• Cursor — .cursor/mcp.json, same mcpServers shape.
• VS Code (Copilot agent mode) — .vscode/mcp.json, top-level key servers (see examples/vscode.mcp.json).

Configuration

Env var	Default	Purpose
ARKO_API_BASE_URL	https://arko.devsecai.io	API origin.
ARKO_TOKEN	(unset)	Static bearer JWT — overrides interactive login (CI/headless).
ARKO_OAUTH_CLIENT_ID	central pool SPA client	Cognito app client used for login.
ARKO_COGNITO_DOMAIN	central pool Hosted UI	Cognito Hosted UI origin.
ARKO_OAUTH_PORT	8765	Loopback callback port (must be registered on the client).
ARKO_CREDENTIALS_PATH	~/.arko/credentials.json	Where the refresh token is cached.
ARKO_TIMEOUT_MS	120000	Per-request timeout.
ARKO_SCAN_WAIT_MS	90000	Max wait for a large async scan.

Roadmap

• Phase 1 — local stdio (default): browser-OAuth login (arko-mcp login), tenant routed by email domain. Works in Claude Code, Cursor, VS Code agent today.
• Phase 2 — remote Streamable HTTP (arko-mcp serve-http, src/http.ts): Claude Code runs the OAuth itself (MCP-native auth, RFC 9728 discovery → Cognito); no local login. Server code + auth gate + discovery are built and tested (npm run httpsmoke); deploy + JWKS hardening are gated — see PHASE-2-REMOTE.md.

# Phase 2, once deployed behind TLS:
claude mcp add --transport http arko https://mcp.arko.devsecai.io/mcp

Layout

packages/mcp/
├── src/
│   ├── index.ts        # entry: dispatch CLI vs MCP server
│   ├── cli.ts          # login / logout / whoami
│   ├── config.ts       # env + OAuth/Cognito config
│   ├── client.ts       # thin ARKO API HTTP client (token-provider backed)
│   ├── tools.ts        # the six MCP tool registrations
│   ├── version.ts
│   └── auth/
│       ├── pkce.ts          # PKCE S256
│       ├── cognito.ts       # Hosted UI authorize + token + refresh
│       ├── loopback.ts      # one-shot localhost callback listener
│       ├── credentials.ts   # ~/.arko store (0600)
│       ├── tokenProvider.ts # cached access token → silent refresh
│       └── login.ts         # interactive flow + identity/tenant lookup
├── scripts/  smoke-test.mjs · auth-test.mjs
├── examples/ .mcp.json · vscode.mcp.json · .env.example
├── ENTERPRISE-SETUP.md
└── README.md