Référence MCP

Serveur MCP — Vue d'ensemble

Le serveur MCP Normi expose 19 outils DVF via le protocole Model Context Protocol (HTTP Streamable). Branchez-le à Claude Desktop, Claude Code, Cline ou tout client MCP compatible.

Connexion

URL du serveurhttps://mcp.normi.fr/mcp

TransportHTTP Streamable (MCP 2024-11-05)

AuthentificationAuthorization: Bearer VOTRE_TOKEN

SessionsTTL 15 min — en mémoire sur Railway

Cycle de vie des sessions

Le serveur maintient les sessions en mémoire. Chaque session a une durée de vie de 15 minutes. À l'expiration (ou après un redéploiement Railway), le serveur répond 409 et le client doit relancer initialize pour obtenir un nouveau mcp-session-id.

Envoyez initialize → récupérez le header mcp-session-id dans la réponse.
Incluez ce header dans toutes les requêtes suivantes.
Sur 409, relancez initialize et reprenez la requête.

Exemple d'initialisation

Requête

curl -X POST https://mcp.normi.fr/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer normi_votre_token" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "mon-agent", "version": "1.0.0" }
    }
  }'

Réponse

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {},
      "prompts": {}
    },
    "serverInfo": {
      "name": "normi-dvf",
      "version": "1.0.0"
    }
  }
}

Appel d'outil (avec session)

curl -X POST https://mcp.normi.fr/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer normi_votre_token" \
  -H "mcp-session-id: SESSION_ID_RETOURNÉ_PAR_INITIALIZE" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_market_stats",
      "arguments": {
        "code_postal": "75011",
        "type_local": "Appartement"
      }
    }
  }'

Les 19 outils MCP

Outil	Crédits	Description
search_properties	5 crédits	Recherche transactions DVF avec filtres
get_market_stats	5 crédits	Stats agrégées : médiane, prix/m², volume
find_comparables	10 crédits	Biens similaires autour d'un point GPS
get_price_trends	10 crédits	Séries temporelles par mois/trimestre/an
compare_neighborhoods	10 crédits	Comparer 2 à 5 zones côte à côte
get_market_activity	10 crédits	Volume d'activité et saisonnalité
get_market_heatmap	15 crédits	Prix par code postal pour un département
get_property_history	20 crédits	Historique complet pour une adresse précise
estimate_property	10 crédits	AVM : fourchette basse/médiane/haute à partir de comparables DVF
get_market_score	10 crédits	Score de santé du marché (0–100) pour une zone
portfolio_add / list / get / update / delete	0–10 crédits	Gérer un portefeuille de biens avec estimations automatiques
alert_create / list / update / delete	0 crédits	Alertes webhook sur nouvelles transactions (Pro/Enterprise)

Crédits

Chaque appel d'outil déduit un nombre fixe de crédits de votre solde. La déduction se fait en arrière-plan après l'exécution réussie (fire-and-forget). Si vos crédits sont insuffisants, l'outil retourne un message d'erreur dans content[0].text — pas d'erreur HTTP 402.

Chaque réponse inclut un champ _credits : { "used": 5, "remaining": 95 }. Un champ note apparaît quand le solde restant est inférieur à 20.

Codes d'erreur HTTP

Code	Cause	Action recommandée
401	Token absent, invalide ou révoqué	Vérifiez is_active sur votre clé API.
409	Session expirée ou introuvable	Le client doit relancer initialize pour obtenir un nouveau session ID.
429	Limite de débit dépassée	60 req/min par défaut. Plans supérieurs : agent 30/min, pro 60/min, enterprise 120/min.

Crédits insuffisants : erreur dans le contenu, pas HTTP

Quand un outil ne peut pas s'exécuter faute de crédits, le serveur retourne HTTP 200 avec un message d'erreur dans content[0].text. Surveillez ce champ dans vos intégrations.

Playground interactif

search_properties