Référence MCP

Serveur MCP — Vue d'ensemble

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

Connexion

URL du serveurhttps://normimcp-server-production.up.railway.app/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://normimcp-server-production.up.railway.app/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://normimcp-server-production.up.railway.app/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": "analyze_market_statistics",
      "arguments": {
        "code_postal": "75011",
        "type_local": "Appartement"
      }
    }
  }'

Les 28 outils MCP

Outil	Crédits	Description
search_property_transactions	5 crédits	Recherche transactions DVF avec filtres
analyze_market_statistics	5 crédits	Stats agrégées : médiane, prix/m², volume
find_property_comparables	10 crédits	Biens similaires autour d'un point GPS
analyze_price_trends	10 crédits	Séries temporelles par mois/trimestre/an
compare_locations	10 crédits	Comparer 2 à 5 zones côte à côte
analyze_market_activity	10 crédits	Volume d'activité et saisonnalité
map_market_prices	15 crédits	Prix par code postal pour un département
lookup_property_history	20 crédits	Historique complet pour une adresse précise
estimate_property_value	10 crédits	AVM : fourchette basse/médiane/haute à partir de comparables DVF
score_market_health	10 crédits	Score de santé du marché (0–100) pour une zone
add_property_to_portfolio / list_portfolio_properties / get_portfolio_property / update_portfolio_property / delete_portfolio_property	0–10 crédits	Gérer un portefeuille de biens avec estimations automatiques
create_market_alert / list_market_alerts / update_market_alert / delete_market_alert	0 crédits	Alertes webhook sur nouvelles transactions (Pro/Enterprise)
analyze_dpe_distribution	10 crédits	Distribution DPE (A–G) et médianes énergétiques pour une zone
analyze_dpe_price_premium	10 crédits	Prime de prix par classe DPE — croisement DVF×DPE cadastral
analyze_dpe_market_impact	10 crédits	Analyse combinée : prix par classe, passoires thermiques, évolution prime verte
get_transaction_building_context	2 crédits	Bâtiment BDNB le plus proche d'une transaction DVF : année, matériaux, usage, étages
analyze_building_age_price_impact	10 crédits	Prix médian/m² par tranche de construction (avant 1919, 1919–1945 … 2006+)
score_renovation_potential	10 crédits	Score de potentiel de rénovation (0–100) : bâtiments anciens sous-valorisés dans la zone
analyze_building_stock	5 crédits	Stock de bâtiments par commune/département : répartition par tranche, usage, logements

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_property_transactions