# Integration — MCP Host

> The native-PHP Model Context Protocol host that lets Claude.ai connect as a client.

_Verified against `app/Http/Controllers/Api/V1/Ai/AiMcpController.php`, `McpToolRegistry`, `McpAuth`, `config/ai.php`, `routes/api.php` on 2026-07-23._

---

## Implementation
- **Native PHP** — implemented inside the Laravel app. **No Node runtime.** The former Node/TypeScript `mcp-server/` directory is **deprecated** (see [`../06-history/deprecated.md`](../06-history/deprecated.md)).
- **Entry point:** `AiMcpController` — Streamable-HTTP JSON-RPC, SSE-aware.
- **Tool registry:** `McpToolRegistry` (authoritative tool catalog) — see [`../03-ai-agents/tools.md`](../03-ai-agents/tools.md).
- **File streaming:** `FileHandler` with mime/disk allowlists (PHP constants); `GET /api/v1/ai/files/{file}`.

## Endpoints (`routes/api.php`)
- `POST/GET/DELETE /api/v1/ai/mcp/read` — read tier.
- `POST/GET/DELETE /api/v1/ai/mcp/full` — full tier (write).
- Plus `ping` and REST mirrors `/api/v1/investors`, `/api/v1/startups`.

## Auth & tiers
- `McpAuth:{read|full}` middleware accepts **OAuth 2.1 bearer** or **legacy Sanctum**.
- Tier is enforced by URL — a `numu:read` token cannot reach `/mcp/full`.
- Backed by the full OAuth 2.1 server (`.well-known/*`, `/oauth/authorize|token|revoke|introspect|userinfo`).
- Detailed permission model in [`../03-ai-agents/permissions.md`](../03-ai-agents/permissions.md).

## Feature gating & status
- Controlled by `config/ai.php` (`NUMU_AI_ENABLED`). When false, `/api/v1/ai/*` returns **404**.
- CORS allow-list defaults to `https://claude.ai`; per-token circuit breaker (`ai.cb`) → 423.
- **Deployment/production availability must not be assumed — Unknown - requires confirmation.**