Outils publics

Le serveur MCP offre trois outils. Tous sont en lecture seule, ne demandent aucun compte et ne renvoient que des données publiées.

Comportement des outilsCopier le lien de cette section

• Lecture seule. Chaque outil est annoté readOnlyHint: true, destructiveHint: false, idempotentHint: true et openWorldHint: false. Les outils ne font que lire le catalogue publié de Matchai.
• Trois parties dans chaque résultat. content est du texte brut qu'un modèle peut citer. structuredContent contient des données typées qui correspondent au outputSchema de l'outil. _meta sert au widget de fiches d'inscription et peut être ignoré par les autres clients.
• Inconnu signifie null. Un fait que le courtier n'a pas indiqué vaut null, jamais 0. Une inscription sans prix indiqué a price: null.
• Des arguments tolérants. Les valeurs null et les chaînes vides sont retirées, et les nombres envoyés sous forme de chaînes, comme "600000" ou "$600,000", sont convertis avant la validation.
• Les erreurs qu'un modèle peut corriger reviennent sous forme de résultat avec isError: true et un message. Un appel qui nomme un outil inconnu, ou dont les arguments ne sont pas un objet, est une erreur JSON-RPC -32602. Voir les erreurs.

L'objet inscriptionCopier le lien de cette section

search_listings et get_professional renvoient des objets inscription, et get_listing renvoie le même objet avec des champs de détail supplémentaires.

search_listingsCopier le lien de cette section

Cherche parmi les inscriptions publiées qui sont disponibles en ce moment. Renvoie jusqu'à 10 inscriptions, la meilleure correspondance d'abord.

EntréeCopier le lien de cette section

Tous les champs sont facultatifs. Sans argument, ce sont les inscriptions mises à jour le plus récemment qui sont renvoyées.

query est lu avec le même analyseur que la recherche d'inscriptions : les prix, les chambres, les salles de bain, la vente ou la location et le type de propriété sont extraits de la phrase, en anglais, en français ou en espagnol. Un argument explicite l'emporte toujours sur ce que dit la phrase, et la phrase complète ce que les arguments ne précisent pas. Si minPrice est plus élevé que maxPrice, les deux valeurs sont interverties.

SortieCopier le lien de cette section

Le texte de content commence par le nombre d'inscriptions et une phrase qui explique leur ordre. Il donne ensuite une entrée par inscription avec le titre, le prix et le type, les données clés, le lieu, le courtier inscripteur et l'URL.

Un résultat vide indique si Matchai a vérifié toutes les inscriptions ou seulement les plus récemment mises à jour. Il n'affirme jamais « il n'en existe aucune » pour une recherche qui n'est pas remontée plus loin. Une ville ou une fourchette de prix permet à la recherche de remonter plus loin.

ExempleCopier le lien de cette section

Envoyez ceci comme requête tools/call :

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_listings",
    "arguments": { "query": "3 bedroom condo in Laval under 600k" }
  }
}

Un résultat abrégé. Cette recherche a trouvé une inscription, et l'objet filters montre comment la phrase a été lue :

{
  "content": [
    {
      "type": "text",
      "text": "1 published listing on Matchai. Results are ordered by relevance to the request and by how recently the listing was updated. No broker can pay to change the order or to be included.\n\n1. Bright 3-bedroom condo near Montmorency metro — $585,000, condo for sale\n   3 bedrooms · 1.5 bathrooms · 1,120 sq ft · Montmorency, Laval, Québec\n   Listed by Alice Tremblay (Agence Exemple)\n   https://alice.matchai.co/bright-condo-montmorency"
    }
  ],
  "structuredContent": {
    "kind": "listings",
    "filters": {
      "keywords": ["laval"],
      "city": null,
      "neighbourhood": null,
      "transaction": null,
      "propertyType": "condo",
      "minPrice": null,
      "maxPrice": 600000,
      "minBedrooms": 3,
      "minBathrooms": null
    },
    "count": 1,
    "listings": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "title": "Bright 3-bedroom condo near Montmorency metro",
        "url": "https://alice.matchai.co/bright-condo-montmorency",
        "price": 585000,
        "currency": "CAD",
        "priceText": "$585,000",
        "transaction": "sale",
        "status": "available",
        "propertyType": "condo",
        "bedrooms": 3,
        "bathrooms": 1.5,
        "livingAreaSqft": 1120,
        "neighbourhood": "Montmorency",
        "city": "Laval",
        "region": "Québec",
        "location": "Montmorency, Laval, Québec",
        "image": "https://media.example.com/listings/bright-condo-montmorency/cover.jpg",
        "broker": { "name": "Alice Tremblay", "brokerage": "Agence Exemple" },
        "site": { "name": "Alice Tremblay Immobilier", "url": "https://alice.matchai.co" },
        "updatedAt": "2026-10-12T14:03:22.000Z"
      }
    ]
  },
  "_meta": {
    "ui": { "resourceUri": "ui://matchai/listing-cards.html?v=3f9a1c2b7d10" }
  }
}

Le véritable objet _meta contient quelques clés de plus pour le widget. Les noms, les adresses et l'hôte des photos de ces exemples sont fictifs.

get_listingCopier le lien de cette section

Renvoie tous les détails publics d'une inscription publiée.

EntréeCopier le lien de cette section

Envoyez url ou id. Si vous envoyez les deux, c'est id qui est utilisé.

Ces adresses désignent toutes la même inscription, avec ou sans barre oblique finale ou paramètres de suivi :

• le site Matchai du courtier, comme https://alice.matchai.co/bright-condo-montmorency;
• l'ancienne forme avec /listing/ devant le slug, comme https://alice.matchai.co/listing/bright-condo-montmorency;
• le domaine propre du courtier, quand le site en a un;
• la forme avec chemin sur la plateforme, comme https://matchai.co/site/alice/bright-condo-montmorency;
• la copie Markdown de n'importe laquelle de ces adresses, qui se termine par .md;
• l'identifiant seul de l'inscription.

SortieCopier le lien de cette section

Les champs supplémentaires de listing :

La recherche ne renvoie que des inscriptions disponibles. get_listing peut aussi renvoyer une inscription publiée qui a depuis été vendue ou louée, alors vérifiez status.

Si aucune inscription publiée ne correspond, le résultat a isError: true et indique que l'inscription n'est peut-être plus publiée ou que l'adresse est peut-être incomplète.

ExempleCopier le lien de cette section

{
  "name": "get_listing",
  "arguments": { "url": "https://alice.matchai.co/bright-condo-montmorency" }
}

Le structuredContent du résultat, abrégé :

{
  "kind": "listing",
  "listing": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "title": "Bright 3-bedroom condo near Montmorency metro",
    "url": "https://alice.matchai.co/bright-condo-montmorency",
    "price": 585000,
    "currency": "CAD",
    "priceText": "$585,000",
    "transaction": "sale",
    "status": "available",
    "propertyType": "condo",
    "bedrooms": 3,
    "bathrooms": 1.5,
    "livingAreaSqft": 1120,
    "neighbourhood": "Montmorency",
    "city": "Laval",
    "region": "Québec",
    "location": "Montmorency, Laval, Québec",
    "image": "https://media.example.com/listings/bright-condo-montmorency/cover.jpg",
    "broker": { "name": "Alice Tremblay", "brokerage": "Agence Exemple" },
    "site": { "name": "Alice Tremblay Immobilier", "url": "https://alice.matchai.co" },
    "updatedAt": "2026-10-12T14:03:22.000Z",
    "description": "A bright corner unit on the fourth floor, five minutes from the metro. …",
    "highlights": ["Two balconies", "Indoor parking", "Five minutes from the metro"],
    "yearBuilt": 2012,
    "lotSizeSqft": null,
    "address": null,
    "postalCode": null,
    "images": [
      "https://media.example.com/listings/bright-condo-montmorency/cover.jpg",
      "https://media.example.com/listings/bright-condo-montmorency/living-room.jpg"
    ],
    "datePosted": "2026-09-30"
  }
}

Ici, le courtier n'a pas publié l'adresse civique, alors address et postalCode valent null.

get_professionalCopier le lien de cette section

Renvoie le profil public d'un courtier avec ses inscriptions disponibles, jusqu'à 10.

EntréeCopier le lien de cette section

Envoyez username ou url. Si vous envoyez les deux, c'est username qui est utilisé.

SortieCopier le lien de cette section

Les champs de professional :

Un courtier n'est renvoyé que s'il a choisi d'être public quelque part : un site publié, une Page Matchai publiée ou une carte professionnelle activée. Sinon, le résultat a isError: true et indique qu'aucun courtier ayant un profil Matchai public ne correspond.

ExempleCopier le lien de cette section

{
  "name": "get_professional",
  "arguments": { "username": "alice_tremblay" }
}

La partie professional du structuredContent du résultat. Le tableau listings à côté contient des objets inscription comme ceux de search_listings.

{
  "name": "Alice Tremblay",
  "username": "alice_tremblay",
  "jobTitle": "Real estate broker",
  "brokerage": "Agence Exemple",
  "licence": { "number": "123456", "body": "OACIQ" },
  "photo": "https://media.example.com/avatars/alice-tremblay.jpg",
  "siteUrl": "https://alice.matchai.co",
  "pageUrl": "https://alice.matchai.pro",
  "contact": { "email": null, "phone": null }
}

Le widget de fiches d'inscriptionCopier le lien de cette section

Quand un outil renvoie des inscriptions, les assistants qui prennent en charge MCP Apps peuvent les afficher sous forme de fiches dans la conversation. Les fiches proviennent d'une seule ressource, vers laquelle pointent tous les outils.

Lisez l'URI actuel dans tools/list au lieu de le coder en dur. resources/read accepte aussi l'URI sans v, ou avec n'importe quel ancien v, et répond avec le widget actuel.

resources/list renvoie cette ressource unique, avec la politique de sécurité du contenu que l'assistant devrait appliquer :

{
  "resources": [
    {
      "uri": "ui://matchai/listing-cards.html?v=3f9a1c2b7d10",
      "name": "listing-cards",
      "title": "Listing cards",
      "description": "Interactive cards for the listings a Matchai tool returned.",
      "mimeType": "text/html;profile=mcp-app",
      "_meta": {
        "ui": {
          "csp": {
            "connectDomains": ["https://matchai.co"],
            "resourceDomains": ["https://matchai.co", "https://media.example.com"]
          },
          "prefersBorder": true
        }
      }
    }
  ]
}

resources/read renvoie le widget sous forme d'un seul document HTML autonome dans contents[0].text. Il n'utilise aucun cadriciel, ni aucune police ou aucun script externe.

Ce que fait le widget :

• Il affiche le résultat selon son type. kind: "listings" devient une rangée défilante de fiches, kind: "listing" devient une fiche plus grande avec une courte description, et kind: "professional" devient le nom et le rôle du courtier, avec un lien Visiter le site, au-dessus d'une rangée de fiches.
• Il suit l'assistant. Il utilise le thème de couleurs et la langue de l'assistant (anglais, français ou espagnol) et ouvre les liens par l'intermédiaire de l'assistant.
• Il gère les échecs. Un résultat avec isError: true, ou sans structuredContent, affiche « Rien à afficher ».
• Il signale qu'une fiche a été vue. Quand une fiche est restée à l'écran assez longtemps pour être lue, le widget indique à Matchai quelles inscriptions étaient visibles, pendant combien de temps et dans quelle proportion, ainsi que le type approximatif de plateforme de l'assistant (Web, ordinateur ou mobile). Si le résultat ne porte aucun jeton pour ce signalement, rien n'est envoyé. Le widget n'envoie jamais le texte de la conversation ni un identifiant d'utilisateur.

Un assistant qui n'affiche pas les MCP Apps ignore le widget. Le texte de content et les données de structuredContent portent toute la réponse. Si vous créez vos propres fiches, reliez chacune à l'url de l'inscription.