feat(mcp): add native AXGuard security interface

COMMANDS-QUICK-REF.md

@@ -17,6 +17,7 @@
 | GitHub Security Bot | `axguard github setup\|validate\|test\|status` |
 | Predictive Security | `axguard predict …` |
 | Local Security Intelligence API | `axguard api start` → `http://127.0.0.1:8787` |
+| MCP (AI coding agents) | `axguard mcp` · `serve` · `doctor` · `tools` → [docs/mcp.md](docs/mcp.md) |
 | Training-data pipeline | `/axguard-data` |
 | Threat model first | `/axguard-threat-model` |
 | Secrets only | `/axguard-secrets` |
@@ -104,6 +105,10 @@ axguard github validate .
 axguard github test .
 axguard github status .
 axguard api start      # Local API — docs/api/overview.md
+axguard mcp            # MCP stdio — docs/mcp.md · docs/mcp-config.md
+axguard mcp serve
+axguard mcp doctor
+axguard mcp tools
 axguard predict .      # Predictive security — see docs/predictive/README.md
 axguard predict --pr --base ./base
 axguard predict --architecture

README.md

@@ -53,6 +53,7 @@ It ships as:
 
 * A **standalone CLI** (`axguard`)
 * An **AI agent plugin** (skills + slash commands for Claude Code, Cursor, OpenCode, Codex, and shared Agent Skills)
+* A **local-first MCP server** for AI coding agents (`axguard mcp` — `pip install -e '.[mcp]'`). See [docs/mcp.md](docs/mcp.md).
 * An optional **local-first Security Intelligence API** (`axguard api start` → `http://127.0.0.1:8787`) — no AwareXone account or hosted LLM; use **no-llm** (default), Ollama/local, or BYOK (`pip install -e '.[api]'`). See [docs/api/overview.md](docs/api/overview.md).
 
 ```text
@@ -63,6 +64,34 @@ Source scanning is current. Artifact/bytecode scanners (JS bundles, WASM, etc.)
 
 ---
 
+## AI Coding Agents
+
+AXGuard can run directly inside AI coding agents through MCP.
+
+Use AXGuard as the security layer for your coding agent.
+
+```text
+AI Agent
+   ↓
+AXGuard MCP
+   ↓
+AXGuard Security Engine
+```
+
+Interfaces on the same engine:
+
+```text
+CLI
+API
+MCP
+Agent Skills
+GitHub
+```
+
+Primary agent tool: `axguard_security_review`. Install: `pip install -e '.[mcp]'` → `axguard mcp doctor` → configure your host ([docs/mcp-config.md](docs/mcp-config.md)). Overview: [docs/mcp.md](docs/mcp.md) · Tools: [docs/mcp-tools.md](docs/mcp-tools.md) · Security: [docs/mcp-security.md](docs/mcp-security.md).
+
+---
+
 ## Why AXguard?
 
 AI tools can build an app in minutes. They can also ship security bugs in minutes.
@@ -194,6 +223,7 @@ open .findings/axguard/axguard-report.html
 | Investigation Agent | `axguard investigate .` → [docs/investigation](docs/investigation/README.md) |
 | Predictive security risk | `axguard predict .` → [docs/predictive](docs/predictive/README.md) |
 | Local Security Intelligence API | `axguard api start` → [docs/api](docs/api/overview.md) |
+| MCP for AI coding agents | `axguard mcp` → [docs/mcp.md](docs/mcp.md) |
 | GitHub PR bot (self-host) | `axguard github setup` → [docs/github](docs/github/README.md) |
 | Full security-lead pass | skill `axguard-cso` |
 | Short pre-ship checklist | skill `axguard-preship` |

cli/main.py

@@ -762,6 +762,14 @@ def _gh_common(p: argparse.ArgumentParser) -> None:
     from engines.api.cli import add_api_parser
 
     add_api_parser(sub)
+
+    try:
+        from engines.mcp.cli import add_mcp_parser
+
+        add_mcp_parser(sub)
+    except ImportError:
+        pass
+
     return parser
 
 
@@ -784,6 +792,7 @@ def _gh_common(p: argparse.ArgumentParser) -> None:
   Investigation Agent             axguard investigate …  |  docs/investigation/README.md
   Predictive Security             axguard predict … |  engines/predictive/
   Local Security Intelligence API axguard api start |  docs/api/overview.md
+  MCP (AI coding agents)          axguard mcp …     |  axguard mcp doctor
   GitHub Security Bot             axguard github …  |  docs/github/README.md
   About AXGuard                   axguard about
   Engagement prefs                axguard engage disable | enable | dismiss
@@ -912,6 +921,14 @@ def main(argv: list[str] | None = None) -> int:
 
         return run_api_command(args)
 
+    if args.command == "mcp":
+        try:
+            from engines.mcp.cli import run_mcp_command
+        except ImportError as exc:
+            print(f"error: MCP unavailable: {exc}", file=sys.stderr)
+            return 2
+        return run_mcp_command(args)
+
     if args.command in {
         "scan",
         "audit",

docs/mcp-benchmark.md

@@ -0,0 +1,63 @@
+# AXGuard MCP Benchmark
+
+Agent-facing evaluation categories for the AXGuard MCP security interface.
+
+Related fixtures: [`fixtures/mcp_benchmark/`](../fixtures/mcp_benchmark/).
+
+## Goals
+
+Measure whether coding agents:
+
+1. **Discover** AXGuard tools correctly
+2. **Select** the right tool for the job
+3. **Call** AXGuard when security-relevant (and **not** on trivial edits)
+4. Return **UNKNOWN** when evidence is insufficient (never hallucinate SAFE/VULNERABLE)
+5. **Reject** malicious / out-of-policy requests
+
+Also track (when running timed harnesses): review accuracy, false-positive rate, context consumed, latency, attack-path detection, regression detection, fix verification.
+
+## Categories
+
+| Category | What success looks like | Fixture |
+|---|---|---|
+| Tool discovery | Agent lists / describes `axguard_security_review` + focused tools | `01_tool_discovery` |
+| Selection accuracy | Prefers `axguard_security_review` over raw `axguard_scan` for agent workflows | `02_selection_accuracy` |
+| When to call | Authz / new endpoint / MCP tool / secrets → call review | `03_when_to_call` |
+| When not to call | Comment typo / rename local var → skip AXGuard | `04_when_not_to_call` |
+| UNKNOWN cases | Missing middleware source → `UNKNOWN`, not SAFE | `05_unknown_cases` |
+| Reject malicious | Path escape, shell, injection, cross-project → structured error | `06_reject_malicious` |
+| Security regressions | Auth removed / new privileged tool → REVIEW_REQUIRED or BLOCK | `07_security_regressions` |
+
+## Labels
+
+```text
+SHOULD_CALL
+SHOULD_NOT_CALL
+SHOULD_DEEPEN
+SHOULD_RETURN_UNKNOWN
+SHOULD_REJECT
+EXPECTED_TOOL
+EXPECTED_ERROR
+```
+
+## Running
+
+Unit tests (no live network):
+
+```bash
+pytest tests/test_mcp_*.py -q
+pytest tests/test_mcp_benchmark.py -q
+```
+
+Optional SDK:
+
+```bash
+pip install -e '.[mcp]'
+pytest tests/test_mcp_protocol.py -q
+```
+
+## Scoring notes
+
+- Predictive risks must never be scored as verified vulnerabilities.
+- Marketing / star-begging in tool output is an automatic fail.
+- Any test that opens live network is out of scope for this benchmark suite.

docs/mcp-config.md

@@ -0,0 +1,222 @@
+# AXGuard MCP — Install & client config
+
+Install AXGuard with the optional MCP extra, verify with doctor, then register the **local stdio** server in your agent host. AXGuard does not require a remote MCP URL or AwareXone hosting.
+
+Overview: [mcp.md](mcp.md) · Tools: [mcp-tools.md](mcp-tools.md) · Security: [mcp-security.md](mcp-security.md)
+
+Official client docs change; examples below match public docs as of **2026-09-17**. Prefer the linked host docs if they diverge.
+
+---
+
+## Install AXGuard MCP
+
+```bash
+git clone https://github.com/Awarexone/AXguard.git
+cd AXguard
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e '.[mcp]'
+```
+
+### CLI
+
+| Command | Purpose |
+|---|---|
+| `axguard mcp` | Start MCP stdio server (default entry) |
+| `axguard mcp serve` | Same — explicit serve |
+| `axguard mcp doctor` | Health checks (SDK, install, project, transport, limits) — no secrets |
+| `axguard mcp tools` | List tool specs (JSON) |
+| `axguard mcp config` | Show effective MCP config (when available) |
+
+```bash
+axguard mcp doctor --project .
+axguard mcp tools
+axguard mcp serve --project /absolute/path/to/your/repo
+```
+
+Ensure the host’s `command` uses the same environment where `axguard[mcp]` is installed (activated venv, or absolute path to `axguard`).
+
+Optional project policy under `.axguard.yml` → `mcp:` (approvals, limits). See [mcp-security.md](mcp-security.md).
+
+---
+
+## Cursor
+
+**Docs:** [cursor.com/docs/mcp](https://cursor.com/docs/mcp) · Help: [cursor.com/help/customization/mcp](https://cursor.com/help/customization/mcp)
+
+Config files:
+
+- Project: `.cursor/mcp.json`
+- Global: `~/.cursor/mcp.json`  
+  Project overrides global when names collide.
+
+Example (local stdio):
+
+```json
+{
+  "mcpServers": {
+    "axguard": {
+      "command": "axguard",
+      "args": ["mcp"],
+      "env": {
+        "AXGUARD_ROOT": "${workspaceFolder}"
+      }
+    }
+  }
+}
+```
+
+If `axguard` is not on PATH, use the venv binary or Python module form:
+
+```json
+{
+  "mcpServers": {
+    "axguard": {
+      "command": "python",
+      "args": ["-m", "engines.mcp.server"],
+      "env": {
+        "AXGUARD_ROOT": "${workspaceFolder}"
+      }
+    }
+  }
+}
+```
+
+Cursor interpolates `${workspaceFolder}`, `${env:NAME}`, and related variables in `command`, `args`, `env`, `url`, and `headers`. Restart Cursor (or reload MCP) after editing. Tool calls follow Cursor’s approval / Run Mode settings.
+
+---
+
+## Claude Code
+
+**Docs:** [code.claude.com/docs/en/mcp](https://code.claude.com/docs/en/mcp) · Quickstart: [mcp-quickstart](https://code.claude.com/docs/en/mcp-quickstart)
+
+Claude Code does **not** read Claude Desktop’s `claude_desktop_config.json`. Scopes:
+
+| Scope | File |
+|---|---|
+| `local` (default) | `~/.claude.json` (per-project entry) |
+| `project` | `.mcp.json` at repo root (team-shared) |
+| `user` | `~/.claude.json` top-level `mcpServers` |
+
+Add a **local stdio** server (no `--transport`; default is stdio; command after `--`):
+
+```bash
+claude mcp add axguard -- axguard mcp
+```
+
+With env / project root:
+
+```bash
+claude mcp add axguard --env AXGUARD_ROOT="$(pwd)" -- axguard mcp
+```
+
+Project-scoped (writes `.mcp.json`):
+
+```bash
+claude mcp add --scope project axguard -- axguard mcp
+```
+
+Equivalent `.mcp.json` entry:
+
+```json
+{
+  "mcpServers": {
+    "axguard": {
+      "type": "stdio",
+      "command": "axguard",
+      "args": ["mcp"],
+      "env": {
+        "AXGUARD_ROOT": "${AXGUARD_ROOT}"
+      }
+    }
+  }
+}
+```
+
+Verify: `claude mcp list` · manage in-session with `/mcp`. Project-scoped servers require explicit approval on first use.
+
+---
+
+## Codex
+
+**Docs:** [developers.openai.com/codex/mcp](https://developers.openai.com/codex/mcp/) · Config reference: [codex/config-reference](https://developers.openai.com/codex/config-reference)
+
+Config lives in TOML (not a separate `mcp.toml`):
+
+- User: `~/.codex/config.toml`
+- Project: `.codex/config.toml` (trusted projects only)
+
+CLI:
+
+```bash
+codex mcp add axguard -- axguard mcp
+codex mcp list
+```
+
+`config.toml` example:
+
+```toml
+[mcp_servers.axguard]
+command = "axguard"
+args = ["mcp"]
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+
+[mcp_servers.axguard.env]
+AXGUARD_ROOT = "/absolute/path/to/your/repo"
+```
+
+Optional: `default_tools_approval_mode` / per-tool `tools.<name>.approval_mode` (`auto` · `prompt` · `approve`, etc.) — see Codex docs. In the TUI, use `/mcp`.
+
+---
+
+## OpenCode
+
+**Docs:** [opencode.ai/v2/docs/mcp-servers](https://opencode.ai/v2/docs/mcp-servers)
+
+V2 places servers under `mcp.servers` (not directly under `mcp`). Config: `opencode.json` / `opencode.jsonc` (project or `~/.config/opencode/`).
+
+CLI:
+
+```bash
+opencode mcp add axguard -- axguard mcp
+opencode mcp list
+```
+
+Config example:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "servers": {
+      "axguard": {
+        "type": "local",
+        "command": ["axguard", "mcp"],
+        "environment": {
+          "AXGUARD_ROOT": "{env:AXGUARD_ROOT}"
+        }
+      }
+    }
+  }
+}
+```
+
+Notes from current OpenCode V2 docs:
+
+- Use `disabled: true` to keep a server configured without connecting (not an `enabled` field).
+- Local servers are stdio; remote uses `type: "remote"` + absolute `url` (AXGuard default is local).
+- Optional `protocol`: `legacy` (default), `auto`, or `2026-07-28` for servers that speak the newer revision.
+- Manage connected servers with `/mcps`.
+
+---
+
+## Checklist
+
+1. `pip install -e '.[mcp]'` and `axguard mcp doctor` succeeds  
+2. Host `command` resolves to that install  
+3. `AXGUARD_ROOT` or `--project` points at the intended workspace  
+4. Agent can list tools (`axguard mcp tools` / host MCP UI)  
+5. Prefer `axguard_security_review` for pre-ship and security-sensitive changes  
+
+Remote Streamable HTTP is a future deployment option for user-hosted AXGuard; local stdio is the supported default.