Serveur MCP Immo API : connectez vos agents IA aux données DVF

Qu'est-ce que le protocole MCP ?

Le Model Context Protocol (MCP) est un standard ouvert qui permet aux modèles de langage (LLM) d'interagir avec des sources de données externes via des outils structurés. Au lieu de copier-coller des données dans un prompt, un agent IA équipé d'un serveur MCP peut directement interroger une API, lire les résultats et les utiliser dans son raisonnement.

Immo API implémente le transport Streamable HTTP du protocole MCP, ce qui signifie que le serveur est stateless : chaque requête est indépendante, sans session à maintenir. C'est l'approche recommandée pour les serveurs MCP distants (remote MCP servers) déployés sur le web. Pour en savoir plus sur l'utilisation de MCP avec les données immobilières, consultez notre article MCP et agents IA : interroger le DVF avec des agents intelligents.

Installation rapide

Le serveur MCP Immo API est accessible à l'adresse https://immoapi.app/api/mcp. Voici comment le connecter selon votre client.

Claude Code

claude mcp add --transport http immoapi \
  https://immoapi.app/api/mcp \
  --header "x-api-key: YOUR_API_KEY"

Cursor

Dans les settings Cursor, ajoutez un serveur MCP avec la configuration suivante :

{
  "mcpServers": {
    "immoapi": {
      "url": "https://immoapi.app/api/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

VS Code (Copilot)

Ajoutez à votre fichier .vscode/mcp.json :

{
  "servers": {
    "immoapi": {
      "type": "http",
      "url": "https://immoapi.app/api/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Windsurf

{
  "mcpServers": {
    "immoapi": {
      "serverUrl": "https://immoapi.app/api/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Client générique (mcp-remote, Python, etc.)

Tout client MCP supportant le transport Streamable HTTP peut se connecter. Le serveur accepte les requêtes POST JSON-RPC à https://immoapi.app/api/mcp avec le header x-api-key pour l'authentification.

Authentification

Le serveur MCP utilise la même clé API que les endpoints REST. Passez votre clé dans le header x-api-key de chaque requête.

curl -X POST "https://immoapi.app/api/mcp" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Obtenez votre clé API en créant un compte sur Immo API. La clé est disponible immédiatement dans votre tableau de bord. Toutes les communications transitent exclusivement via HTTPS. Ne partagez jamais votre clé API dans un dépôt public ou du code côté client.

Outils MCP disponibles

Le serveur MCP Immo API expose 3 outils que vos agents IA DVF peuvent appeler pour interroger les données immobilières. Chaque outil est en lecture seule (readOnly) et idempotent. Ils correspondent aux endpoints REST équivalents de l'API.

Les outils sont découverts automatiquement par les clients MCP via la méthode tools/list.

Recherche des transactions immobilières DVF en France par commune, code postal, année, type de bien et fourchette de prix. Pagination incluse.

Paramètres

Exemple d'appel JSON-RPC

curl -X POST "https://immoapi.app/api/mcp" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search_mutations",
      "arguments": {
        "commune": "Paris",
        "type_local": "Appartement",
        "annee": 2024,
        "prix_min": 200000,
        "prix_max": 600000,
        "limit": 5
      }
    }
  }'

Exemple de réponse

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\n  \"date_mutation\": \"2024-03-15\",\n  ...}]"
      }
    ],
    "structuredContent": {
      "result": [
        {
          "date_mutation": "2024-03-15",
          "valeur_fonciere": 485000,
          "adresse": "12 Rue de Rivoli, 75001 Paris",
          "type_local": "Appartement",
          "surface_reelle_bati": 65,
          "nombre_pieces": 3,
          "prix_m2": 7461
        }
      ]
    }
  }
}

Recherche les ventes comparables DVF autour de coordonnées GPS ou du centre moyen d'un code postal. Idéal pour les estimations immobilières par proximité.

Paramètres

Au moins un des paramètres code_postal ou la paire lat/lng est requis.

Exemple d'appel JSON-RPC

curl -X POST "https://immoapi.app/api/mcp" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_nearby_mutations",
      "arguments": {
        "lat": 48.8566,
        "lng": 2.3522,
        "radius_km": 1,
        "type_local": "Appartement",
        "annee": 2024,
        "limit": 10
      }
    }
  }'

Exemple de réponse

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "..." }],
    "structuredContent": {
      "result": {
        "center": { "lat": 48.8566, "lng": 2.3522 },
        "radius_km": 1,
        "mutations": [
          {
            "date_mutation": "2024-02-20",
            "valeur_fonciere": 520000,
            "adresse": "5 Place du Chatelet, 75001 Paris",
            "type_local": "Appartement",
            "surface_reelle_bati": 55,
            "prix_m2": 9454,
            "distance_km": 0.12
          }
        ]
      }
    }
  }
}

Retourne des agrégats DVF simples : nombre de mutations, prix moyen, prix min/max et surface moyenne pour une commune ou un code postal.

Paramètres

Exemple d'appel JSON-RPC

curl -X POST "https://immoapi.app/api/mcp" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "get_market_stats",
      "arguments": {
        "code_postal": "75001"
      }
    }
  }'

Exemple de réponse

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [{ "type": "text", "text": "..." }],
    "structuredContent": {
      "result": {
        "nombre_mutations": 842,
        "prix_moyen": 685000,
        "prix_min": 125000,
        "prix_max": 3200000,
        "surface_moyenne": 52
      }
    }
  }
}

Versions du protocole MCP

Le serveur MCP Immo API supporte plusieurs versions du protocole MCP. Envoyez le header MCP-Protocol-Version pour spécifier la version souhaitée. La version 2025-11-25 ajoute le support de structuredContent dans les réponses d'outils et les annotations de tools. Les versions antérieures restent compatibles mais ne bénéficient pas de ces fonctionnalités.

Limites de requêtes MCP

Le serveur MCP Immo API applique un rate limit dédié de 60 requêtes par minute par clé API. Ce compteur est indépendant des limites des endpoints REST (1 000 requêtes/jour pour le plan Starter, illimité pour le plan Pro).

En cas de dépassement, le serveur retourne un code JSON-RPC -32029 avec un HTTP 429 et un header Retry-After. Attendez le nombre de secondes indiqué avant de renvoyer une requête.

Gestion des erreurs

Le serveur MCP retourne des erreurs au format JSON-RPC 2.0 standard. Voici les codes d'erreur spécifiques :

Exemple d'erreur

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32003,
    "message": "Invalid API key"
  }
}

Cas d'usage pour agents IA

Le serveur MCP Immo API permet à vos agents IA de réaliser des tâches immobilières complexes en autonomie. Voici des exemples concrets d'utilisation :

FAQ

Qu'est-ce qu'un serveur MCP et pourquoi l'utiliser pour les données immobilières ?

Un serveur MCP (Model Context Protocol) est une interface standard qui permet aux agents IA comme Claude, GPT ou Gemini d'accéder à des données externes de manière structurée. Pour les données immobilières DVF, cela signifie que votre agent IA peut rechercher des transactions, comparer des prix et calculer des statistiques sans intervention humaine, directement depuis votre IDE ou votre application.

Le serveur MCP Immo API supporte-t-il le transport SSE ?

Non. Le serveur MCP Immo API utilise le transport Streamable HTTP (POST JSON-RPC) et est entièrement stateless. Les requêtes GET avec Accept: text/event-stream retournent une erreur 405. Ce choix de design garantit la scalabilité et la fiabilité du serveur.

Puis-je utiliser la même clé API pour le MCP et l'API REST ?

Oui. La même clé API fonctionne pour le serveur MCP et les endpoints REST classiques. Les rate limits sont cependant séparés : 60 requêtes/minute pour le MCP, et les limites de votre plan tarifaire (1 000/jour pour Starter, illimité pour Pro) pour l'API REST.

Quels clients MCP sont compatibles avec Immo API ?

Tout client supportant le transport Streamable HTTP du protocole MCP est compatible. Cela inclut Claude Code, Cursor, VS Code (Copilot), Windsurf, le bridge mcp-remote, et les SDK Python/TypeScript MCP.

Les données DVF accessibles via MCP sont-elles les mêmes que via l'API REST ?

Oui, exactement. Le serveur MCP interroge la même base de données DVF que les endpoints REST. Les données sont issues des Demandes de Valeurs Foncières publiées par la DGFiP, couvrant les transactions immobilières en France depuis 2014 (hors Alsace-Moselle et Mayotte).

Comment tester le serveur MCP sans client MCP ?

Vous pouvez tester directement avec curl ou tout outil HTTP. Envoyez des requêtes POST JSON-RPC à https://immoapi.app/api/mcp avec votre clé API dans le header x-api-key. Les exemples de cette documentation montrent les commandes curl pour chaque outil.