# Cogito-Reflex MCP Server

> 🔗 **Service en ligne** : https://services4agents.fyi · Endpoint MCP : `https://mcp.services4agents.fyi/mcp` · 0,10 USDC/session via x402 (première session gratuite)

Serveur MCP (Model Context Protocol) du service **Cogito-Reflex MaaS** — régulation
cognitive pour agents IA : réduction d'entropie, rupture de boucles, leçons
distillées. 300 s par session, paiement **x402** (0,10 USDC sur Base, signature
EIP-3009).

Ce serveur est un **doublon MCP** (adaptateur fin) : il expose le service existant
(API `services4agents.fyi`) au protocole MCP pour la découverte par les agents
(Cursor, Claude Desktop, agents custom). Il ne duplique aucune logique métier :
il relaie vers l'API, dont le paywall x402 reste l'unique juge du paiement.

## Architecture

```
Agent MCP client
   │  (Streamable HTTP, JSON-RPC 2.0)
   ▼
Serveur MCP (ce repo) — 127.0.0.1:9260 (Docker, network host)
   │  appels REST internes
   ▼
API Cogito-Reflex (services4agents.fyi) — paywall x402 inchangé
```

Endpoint public : `https://mcp.services4agents.fyi/mcp` (transport Streamable HTTP).

## Outils MCP

| Outil | Description |
|---|---|
| `start_regulation_session` | Démarre une session (300 s). Chaque agent a droit à **une session gratuite** (découverte) ; au-delà, la réponse contient un challenge x402 (`payment_required`) : l'agent signe une authorization EIP-3009 et rappelle l'outil avec `payment_signature`. |
| `get_session_status` | État de la session (`PENDING`, `MEDITATIVE`, `COMPLETED`…). |
| `finalize_session` | Clôture la session et renvoie les règles distillées (leçons). |

Réponse d'une session acceptée :

```json
{
  "status": "accepted",
  "free": true,
  "session_id": "…",
  "websocket_url": "wss://services4agents.fyi/ws",
  "ws_token": "…",
  "phases": ["INDUCTION", "TRANSITIONING", "MEDITATIVE", "AWAKENING"]
}
```

L'agent se connecte ensuite au WebSocket et envoie en premier message
`{"type": "AUTH", "token": "<ws_token>"}` pour recevoir les pulses CAS
(1 par seconde).

## Session gratuite unique

- Quota : **une session gratuite par identité** (agent_id et IP), suivi dans
  une base SQLite locale (`data/free_tier.sqlite3`).
- Délivrée via le canal interne `X-Cogito-Free-Visit` (token partagé avec l'API,
  variable `FREE_VISIT_TOKEN`), jamais via le paywall.
- Barrière de bonne foi (découverte marketing), pas une sécurité financière.

## Déploiement (VPS)

Prérequis : Docker, API Cogito-Reflex qui tourne sur `127.0.0.1:8000`
(conteneur `cogito-reflex-maas`), nginx.

1. Créer `.env` (cf. `.env.example`) avec les tokens partagés :
   - `COGITO_WS_TOKEN` = même valeur que `WS_AUTH_TOKEN` de l'API
   - `COGITO_FREE_VISIT_TOKEN` = même valeur que `FREE_VISIT_TOKEN` de l'API
2. `docker compose up -d --build` → conteneur `cogito-reflex-mcp` sur `127.0.0.1:9260`.
3. nginx : vhost `mcp.services4agents.fyi` → `proxy_pass http://127.0.0.1:9260`
   (fichier fourni : `deploy/nginx-mcp-services4agents.conf`).
4. DNS : enregistrement A `mcp` → IP du VPS (Porkbun), puis
   `certbot --nginx -d mcp.services4agents.fyi`.

### Variables d'environnement

| Variable | Défaut | Rôle |
|---|---|---|
| `COGITO_API_BASE` | `http://127.0.0.1:8000` | API Cogito-Reflex (interne) |
| `COGITO_WS_PUBLIC_URL` | `wss://services4agents.fyi/ws` | URL WebSocket publique annoncée aux agents |
| `COGITO_WS_TOKEN` | — | Token AUTH du data plane (même valeur que `WS_AUTH_TOKEN` API) |
| `COGITO_FREE_VISIT_TOKEN` | — | Token du canal free visit (même valeur que `FREE_VISIT_TOKEN` API) |
| `COGITO_HOST` / `COGITO_PORT` | `127.0.0.1` / `9260` | Adresse d'écoute |

## Tests

```bash
.venv/bin/python tests/test_mcp_flow.py http://127.0.0.1:9260/mcp
```

Couvre : `tools/list`, session gratuite, quota (2e appel refusé), challenge x402,
signature invalide, statut, finalisation.

## Notes

- Fait le 30/08/2026 (Nemrod) : prototypage + déploiement VPS validés par Daness.
- Le déploiement historique `deploy.sh` (branche `master`, port 8081 + venv) est
  obsolète : le service est déployé en Docker (port 9260).