Connect'O — MCP & OAuth agents

Connect'O expose les données Wast-O aux agents (Cursor, automatisations SI) via un serveur MCP dédié, authentifié en OAuth2 client_credentials.

Différence avec l’API publique

L’API publique /public reste anonyme et lecture seule citoyenne.
Connect'O = credentials machine liés à un cityGroupId, scopes, audit, et écritures bornées optionnelles.

Endpoints

	URL
MCP (Streamable HTTP)	https://mcp.wast-o.com/mcp
Health	https://mcp.wast-o.com/health
Protected Resource Metadata	https://mcp.wast-o.com/.well-known/oauth-protected-resource
AS Metadata	https://api.wast-o.com/.well-known/oauth-authorization-server
Authorize	https://api.wast-o.com/oauth/authorize
Token OAuth	https://api.wast-o.com/oauth/token
DCR	POST https://api.wast-o.com/oauth/register
Consent UI	https://console.wast-o.com/oauth/connecto/authorize
Qui suis-je	GET https://api.wast-o.com/oauth/me

Modes d’auth

A. Agent interactif (Cursor) — DCR + PKCE

1. Le client MCP découvre l’AS via Protected Resource Metadata.
2. DCR (POST /oauth/register) → client_id public.
3. GET /oauth/authorize (PKCE) → redirection vers la page consent console.
4. L’utilisateur se connecte (si besoin), choisit un CityGroup Connect'O, confirme.
5. Redirect code → échange token → Bearer sur /mcp.

B. Machine / SI — client_credentials

1. Console Wast-O → Paramètres → Connect'O.
2. Activer le module Connect'O sur le groupement (si besoin).
3. Nouveau client → copier client_id / client_secret (secret affiché une seule fois).
4. Scopes :
   • wasto.mcp.read (défaut) — lectures référentiel, carto, challenges, terrain agrégé
   • wasto.mcp.write — upserts bornés (dry-run par défaut)

Obtenir un access token (machine)

curl -s -X POST https://api.wast-o.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "wasto_cc_…",
    "client_secret": "…"
  }'

Réponse typique :

{
  "access_token": "eyJ…",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "wasto.mcp.read"
}

Auth Basic (client_id:client_secret) est aussi acceptée.

attention

Ne pas utiliser un JWT console utilisateur comme credential agent. Les tokens machine ont typ=oauth_cc et sont refusés sur les routes admin JWT.

Brancher Cursor / MCP

Dans ~/.cursor/mcp.json :

{
  "mcpServers": {
    "wasto-connect": {
      "type": "http",
      "url": "https://mcp.wast-o.com/mcp"
    }
  }
}

Cursor découvre OAuth (PRM → AS → DCR), ouvre le navigateur sur la page consent Connect'O (choix CityGroup), puis envoie le Bearer automatiquement.

Variables optionnelles côté serveur wasto-mcp (mode machine sans DCR) :

Variable	Rôle
WASTO_API_URL	https://api.wast-o.com
WASTO_CLIENT_ID	client_id Connect'O machine
WASTO_CLIENT_SECRET	secret
WASTO_MCP_RESOURCE_URL	Resource PRM (défaut https://mcp.wast-o.com/mcp)

API / console :

Variable	Rôle
API_PUBLIC_URL / OAUTH_ISSUER	Issuer AS
CONSOLE_PUBLIC_URL	URL page consent

Tools (aperçu)

Lecture

• Contexte : wasto_whoami, city group / context
• Référentiel & carto : waste_types_list, collection_places_list, recycling_points_list
• Engagement : challenges_*
• Terrain agrégé (sans PII) : surveys_list, surveys_overview, survey_responses_summary, field_reports_summary

Écritures (scope write)

waste_type_upsert, recycling_point_upsert, challenge_upsert
→ dryRun par défaut ; confirm=true pour commit. Pas de delete.

Endpoints OAuth métier (référence)

Préfixe Bearer OAuth : /oauth/mcp/…

Méthode	Path	Notes
POST	/oauth/mcp/waste-types/upsert	dryRun / confirm
POST	/oauth/mcp/recycling-points/upsert	dryRun / confirm
POST	/oauth/mcp/challenges/upsert	dryRun / confirm
GET	/oauth/mcp/surveys	métadonnées
GET	/oauth/mcp/surveys/overview	compteurs
GET	/oauth/mcp/surveys/:id/stats	stats choix/notes — pas de texte libre
GET	/oauth/mcp/field-reports/summary	compteurs par statut

Sécurité & offre

• Binding hard : un client = un cityGroupId.
• Module dashboard CONNECTO obligatoire pour émettre / utiliser un client.
• Hors offre gratuite self-serve (ADR-001).
• Révocation immédiate depuis la console.

Voir aussi

• Introduction API publique
• Client SDK
• Guide utilisateur : Gérer Connect'O