# MCP.md — MCP consumer adapter for Numu Angels (thin router)

> Operating rules for any MCP consumer (e.g. Claude.ai) connecting to this project's native-PHP MCP host. **Thin adapter:** it states the MCP-consumer contract and routes to canonical knowledge — it does **not** duplicate the tool catalog, permission model, or endpoint details (those live once in the Engineering Platform KB).


> **Platform source of truth:** `https://dev.azure.com/numuinvestment/numu/_git/numu-engineering-platform`.
> The local folder is only a working copy — **`git pull` it before every task**, and **commit + push** any change you make inside it.
> Missing it? `git clone https://dev.azure.com/numuinvestment/numu/_git/numu-engineering-platform engineering-platform` as a sibling of this repository.

## Governance first
Any **engineering change** to the MCP layer (tools, permissions, endpoints, gating) MUST follow the canonical workflow — see [`AGENTS.md`](AGENTS.md) and `` `<platform>/01-foundation/ai-workflow.md` `` (locate `<platform>` via `AGENTS.md`). This file governs runtime **consumers**, not how the code is changed.

## MCP consumers must (contract — load the details from the KB, never assume them)
- **Use registered tools only** — every call maps to a registered tool; no free-form or unregistered operations.
- **Obey the two-gate permission model** — both the token ability **and** the Admin permission must allow the action.
- **Respect the read/full tiers** — read and full are separate endpoints; a read token cannot reach full. **Full-tier writes apply immediately** and run the entire business workflow (group move + notifications + meeting cancel + audit).
- **Never bypass business services** — tools delegate to the canonical REST controllers and action services; do not reach data outside them.
- **Honor gating & limits** — the host is feature-gated and protected by a per-token circuit breaker; treat the resulting 404 / 423 as designed responses, not errors to route around.

## Canonical references (Engineering Platform — read, do not restate here)
- `` `<platform>/02-projects/numu-angels/integrations/mcp.md` `` — host implementation, endpoints, auth, feature gating.
- `` `<platform>/02-projects/numu-angels/ai-agents/tools.md` `` — tool catalog and tiers.
- `` `<platform>/02-projects/numu-angels/ai-agents/permissions.md` `` — the two-gate permission model (exact abilities/permissions).
- `` `<platform>/02-projects/numu-angels/features/mcp.md` `` — the MCP feature end-to-end.

Locate `<platform>` per [`AGENTS.md`](AGENTS.md); if it cannot be found, apply that file's knowledge-location failure behavior (stop + request the location; never fall back to legacy `docs/ai/`). Deployment/production availability of the AI/MCP layer **must not be assumed** — confirm in the KB.