Update docs: add MCP to README, SECURITY, and ARCHITECTURE

README.md:
- Added MCP Server to Core features
- Updated architecture diagram with MCP client path
- Updated health/metrics descriptions with MCP fields
- Added MCP Bearer auth to Security section

SECURITY.md:
- New "MCP Server Authentication" section: Bearer token management,
  policy enforcement, resource filtering, audit logging, hardening

ALEXCLAW_ARCHITECTURE.md:
- Added mcp/ and plugs/mcp_*.ex to Project Structure
- Added anubis_mcp and nostrum to Dependencies

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: thatsme

ALEXCLAW_ARCHITECTURE.md

@@ -623,6 +623,10 @@ lib/
     scheduler.ex               # Quantum cron scheduler
     skill.ex                   # Skill behaviour definition
     skill_supervisor.ex        # DynamicSupervisor for skill workers
+    mcp/
+      server.ex                # MCP server — Anubis callbacks, tool calls, resource reads
+      tool_schema.ex           # Maps skills/workflows to MCP tool definitions (Peri format)
+      resource_provider.ex     # Routes resource URIs to context modules
   alex_claw_web/
     controllers/
       auth_controller.ex       # Login/logout with rate limiting
@@ -634,6 +638,8 @@ lib/
     live/admin_live/           # LiveView pages (12 pages, .ex logic + .html.heex templates)
     plugs/
       caching_body_reader.ex   # Caches raw body for webhook HMAC verification
+      mcp_auth.ex              # Bearer token auth for /mcp endpoint
+      mcp_forward.ex           # Runtime forwarder to Anubis StreamableHTTP Plug
       rate_limit.ex            # Plug for POST /login rate limiting
       require_auth.ex          # Session-based auth guard
     router.ex
@@ -671,6 +677,8 @@ config/
 {:quantum, "~> 3.5"}          # Cron scheduler
 {:nimble_totp, "~> 1.0"}      # TOTP 2FA
 {:eqrcode, "~> 0.2"}          # QR code generation for 2FA setup
+{:anubis_mcp, "~> 1.0"}       # MCP server (Streamable HTTP transport)
+{:nostrum, "~> 0.10"}          # Discord gateway
 {:jason, "~> 1.4"}            # JSON
 {:telemetry_metrics, "~> 1.0"}
 {:telemetry_poller, "~> 1.0"}

README.md

@@ -27,6 +27,7 @@ AlexClaw monitors the world (RSS feeds, web sources, GitHub repositories, APIs),
 - **Knowledge Base RAG** — Separate `knowledge_entries` table for documentation and reference material, isolated from news/conversation memory. Scraper skills fetch, chunk, and embed documentation from hexdocs.pm, Erlang/OTP source (GitHub), Elixir stdlib source, Learn You Some Erlang, and existing skill code. Chat integrates both Knowledge and Memory search with a context source selector. ~7200 embeddings across 6 knowledge kinds.
 - **Cron Scheduler** — Quantum-based. Jobs defined in config or DB.
 - **Multi-Node BEAM Clustering** — Multiple AlexClaw instances connected via Erlang distribution. Each node runs its own executor independently; nodes exchange workflow outputs via `send_to_workflow` and `receive_from_workflow` skills. Auto-discovery, node status monitoring, and per-workflow node assignment from the admin UI. `docker-compose_swarm.yml` included for local multi-node testing.
+- **MCP Server** — Model Context Protocol server exposes all skills and workflows as MCP tools, and internal data (knowledge, memory, workflows, runs, config) as MCP resources. External AI clients (Claude Code, Cursor, Claude Desktop) can discover and invoke AlexClaw capabilities via the `/mcp` endpoint. Bearer token auth, policy-based tool restrictions, dynamic tool list refresh via PubSub. Built on `anubis_mcp` with Streamable HTTP transport.
 
 ### Skills
 
@@ -107,8 +108,8 @@ AlexClaw can review pull requests and commits for security issues:
 
 ### Observability
 
-- **Health endpoint** — `GET /health` (unauthenticated) returns `{"status":"ok","version":"...","db":"connected"}` for load balancers and Docker healthchecks. Returns HTTP 503 when the database is unreachable.
-- **Metrics endpoint** — `GET /metrics` (authenticated) returns a JSON payload with system stats (uptime, memory, BEAM processes), LLM provider usage, workflow run counts, skill and circuit breaker states, log severity counts, and knowledge/memory entry counts.
+- **Health endpoint** — `GET /health` (unauthenticated) returns `{"status":"ok","version":"...","db":"connected","mcp":"running"}` for load balancers and Docker healthchecks. Returns HTTP 503 when the database is unreachable.
+- **Metrics endpoint** — `GET /metrics` (authenticated) returns a JSON payload with system stats (uptime, memory, BEAM processes), LLM provider usage, workflow run counts, skill and circuit breaker states, MCP status and tool count, log severity counts, and knowledge/memory entry counts.
 
 ### Database Backups
 
@@ -127,7 +128,8 @@ Automated PostgreSQL backups via the `db_backup` core skill. Backups are gzip-co
 - **HMAC-SHA256 webhook verification** — GitHub webhook endpoint uses `Plug.Crypto.secure_compare` for timing-safe signature validation
 - **Encryption at rest** — API keys and tokens are AES-256-GCM encrypted in PostgreSQL, decrypted transparently at runtime
 - **Sensitive key masking** — API keys and tokens show partial values in the admin UI
-- **Agent authorization layer** — Context-aware PolicyEngine with HMAC capability tokens, chain-depth enforcement, process isolation for dynamic skills, configurable policy rules (rate_limit, time_window, chain_restriction, permission_override), and persistent audit logging
+- **Agent authorization layer** — Context-aware PolicyEngine with HMAC capability tokens, chain-depth enforcement, process isolation for dynamic skills, configurable policy rules (rate_limit, time_window, chain_restriction, permission_override, mcp_restriction), and persistent audit logging
+- **MCP Bearer token auth** — MCP endpoint requires `Authorization: Bearer <token>` validated against `mcp.api_key` via constant-time comparison. Policy-based tool restrictions allow blocking specific tools for MCP clients. Sensitive config values are redacted in MCP resource responses
 - **Shell command security** — 5-layer defense: disabled by default, 2FA gate, whitelist with word-boundary check, blocklist for shell metacharacters, no shell interpretation (`System.cmd/3` with args as list), configurable timeout + output truncation
 
 ---
@@ -137,6 +139,7 @@ Automated PostgreSQL backups via the `db_backup` core skill. Backups are gzip-co
 ```
 Telegram <──> TelegramGateway ──┐
 Discord  <──> DiscordGateway  ──┼──> Router ──> Dispatcher ──> Skills
+MCP Client <──> MCP.Server ────┘
                                 │
 Admin UI (Chat) ──────> SkillSupervisor ──> Dynamic Skills
                        (DynamicSupervisor)

SECURITY.md

@@ -66,6 +66,33 @@ Set `github.webhook_secret` in Admin > Config (GitHub category).
 
 ---
 
+## MCP Server Authentication
+
+The MCP endpoint (`/mcp`) exposes AlexClaw skills, workflows, and data to external AI clients (Claude Code, Cursor, Claude Desktop) via the Model Context Protocol.
+
+**Bearer token auth:** Every MCP request must include `Authorization: Bearer <token>`. The token is validated against `mcp.api_key` stored in Admin > Config using `Plug.Crypto.secure_compare/2` (constant-time comparison, no timing attacks). Requests without a valid token receive 401.
+
+**Token management:**
+- Store the API key encrypted in PostgreSQL (`sensitive: true` on the config setting)
+- No automatic expiration — treat MCP tokens like long-lived API keys
+- Rotate by updating `mcp.api_key` in Admin > Config — all previous tokens are immediately invalidated
+- If compromised: rotate immediately in Admin > Config
+
+**Policy enforcement:** MCP tool calls pass through `PolicyEngine.evaluate/2` with `:mcp` caller type. The `mcp_restriction` policy rule type blocks tools by name pattern — insert a policy with `rule_type: "mcp_restriction"` and `config: {"tool_pattern": "shell", "action": "deny"}` to block any tool matching that pattern.
+
+**Resource filtering:** Sensitive config values (API keys, OAuth tokens) are redacted in MCP resource responses — only `[REDACTED]` is returned for settings marked `sensitive: true`.
+
+**Audit logging:** All MCP tool invocations are logged to `auth_audit_log` with caller `mcp:<tool_name>`, visible in Admin > Policies > Audit Log.
+
+**Hardening recommendations:**
+- The `/mcp` endpoint must be behind TLS — never transmit Bearer tokens over plain HTTP
+- Store the MCP API key in your client's config securely (environment variable or encrypted config)
+- Monitor the Audit Log for unexpected MCP activity
+- Use `mcp_restriction` policies to limit which tools are available to MCP clients
+- If MCP is not needed, do not set `mcp.api_key` — the auth plug rejects all requests when the key is unconfigured
+
+---
+
 ## Inter-Node Authentication (Clustering)
 
 Multi-node clusters authenticate via BEAM's distributed Erlang protocol: