Herramientas públicas

El servidor MCP ofrece tres herramientas. Todas son de solo lectura, no necesitan cuenta y solo devuelven datos publicados.

Cómo se comportan las herramientasCopiar el enlace de esta sección

• Solo lectura. Cada herramienta está anotada con readOnlyHint: true, destructiveHint: false, idempotentHint: true y openWorldHint: false. Solo leen el catálogo publicado de Matchai.
• Tres partes en cada resultado. content es texto plano que un modelo puede citar. structuredContent son datos tipados que corresponden al outputSchema de la herramienta. _meta es para el widget de tarjetas de anuncios, y los demás clientes pueden ignorarlo.
• Lo desconocido es null. Un dato que el corredor no indicó es null, nunca 0. Un anuncio sin precio indicado tiene price: null.
• Argumentos flexibles. Los valores null y las cadenas vacías se descartan, y los números enviados como cadenas, como "600000" o "$600,000", se convierten antes de la validación.
• Los errores que un modelo puede corregir vuelven como un resultado con isError: true y un mensaje. Una llamada que nombra una herramienta desconocida, o cuyo arguments no es un objeto, es un error JSON-RPC -32602. Consulta los errores.

El objeto de anuncioCopiar el enlace de esta sección

search_listings y get_professional devuelven objetos de anuncio, y get_listing devuelve el mismo objeto con campos de detalle adicionales.

search_listingsCopiar el enlace de esta sección

Busca anuncios publicados que están disponibles en este momento. Devuelve hasta 10, primero la mejor coincidencia.

EntradaCopiar el enlace de esta sección

Todos los campos son opcionales. Sin argumentos, se devuelven los anuncios actualizados más recientemente.

query se interpreta con el mismo analizador que la búsqueda de anuncios: los precios, las habitaciones, los baños, la venta o el alquiler y el tipo de propiedad se extraen de la frase, en inglés, francés o español. Un argumento explícito siempre prevalece sobre lo que dice la frase, y la frase completa lo que los argumentos omiten. Si minPrice es mayor que maxPrice, se intercambian.

SalidaCopiar el enlace de esta sección

El texto de content empieza con la cantidad de anuncios y una indicación de cómo están ordenados. Luego enumera una entrada por anuncio con el título, el precio y el tipo, los datos, el lugar, el corredor del anuncio y la URL.

Un resultado vacío indica si Matchai revisó todos los anuncios o solo los actualizados más recientemente. Nunca afirma que "no existe ninguno" en una búsqueda que no llegó más atrás. Una ciudad o un rango de precios permite que la búsqueda llegue más lejos.

EjemploCopiar el enlace de esta sección

Envía esto como una solicitud tools/call:

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

Un resultado abreviado. Esta búsqueda encontró un anuncio, y el objeto filters muestra cómo se interpretó la frase:

{
  "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" }
  }
}

El objeto _meta real tiene algunas claves más para el widget. Los nombres, las direcciones y el host de las fotos de estos ejemplos son ficticios.

get_listingCopiar el enlace de esta sección

Devuelve todos los detalles públicos de un anuncio publicado.

EntradaCopiar el enlace de esta sección

Envía url o id. Si envías ambos, se usa id.

Todas estas direcciones nombran el mismo anuncio, con o sin barra final o parámetros de seguimiento:

• el sitio de Matchai del corredor, como https://alice.matchai.co/bright-condo-montmorency;
• la forma anterior con /listing/ antes del slug, como https://alice.matchai.co/listing/bright-condo-montmorency;
• el dominio propio del corredor, cuando el sitio tiene uno;
• la forma de ruta en la plataforma, como https://matchai.co/site/alice/bright-condo-montmorency;
• la copia en Markdown de cualquiera de ellas, terminada en .md;
• el id del anuncio por sí solo.

SalidaCopiar el enlace de esta sección

Los campos adicionales de listing:

La búsqueda solo devuelve anuncios disponibles. get_listing también puede devolver un anuncio publicado que desde entonces se haya vendido o alquilado, así que revisa status.

Si ningún anuncio publicado coincide, el resultado tiene isError: true e indica que es posible que el anuncio se haya dejado de publicar o que la dirección esté incompleta.

EjemploCopiar el enlace de esta sección

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

El structuredContent del resultado, abreviado:

{
  "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"
  }
}

Aquí el corredor no publicó la dirección, así que address y postalCode son null.

get_professionalCopiar el enlace de esta sección

Devuelve el perfil público de un corredor con sus anuncios disponibles, hasta 10.

EntradaCopiar el enlace de esta sección

Envía username o url. Si envías ambos, se usa username.

SalidaCopiar el enlace de esta sección

Los campos de professional:

Un corredor se devuelve solo si eligió ser público en algún lugar: un sitio publicado, una Página Matchai publicada o una tarjeta de presentación activada. De lo contrario, el resultado tiene isError: true e indica que ningún corredor con un perfil público de Matchai coincide.

EjemploCopiar el enlace de esta sección

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

La parte professional del structuredContent del resultado. El array listings que la acompaña contiene objetos de anuncio como los 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 }
}

El widget de tarjetas de anunciosCopiar el enlace de esta sección

Cuando una herramienta devuelve anuncios, los asistentes compatibles con MCP Apps pueden mostrarlos como tarjetas dentro de la conversación. Las tarjetas provienen de un único recurso al que apuntan todas las herramientas.

Lee el URI actual en tools/list en lugar de escribirlo directamente en el código. resources/read también acepta el URI sin v, y cualquier v anterior, y responde con el widget actual.

resources/list devuelve ese único recurso, incluida la política de seguridad de contenido que debe aplicar el asistente:

{
  "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 devuelve el widget como un único documento HTML autónomo en contents[0].text. No usa ningún framework ni ninguna fuente o script externos.

Qué hace el widget:

• Muestra el resultado según su tipo. kind: "listings" se convierte en una fila desplazable de tarjetas, kind: "listing" en una tarjeta más grande con una descripción breve, y kind: "professional" en el nombre y el cargo del corredor con un enlace Visitar el sitio, sobre una fila de tarjetas.
• Se adapta al asistente. Usa el tema de colores y el idioma del asistente (inglés, francés o español) y abre los enlaces a través del asistente.
• Gestiona los fallos. Un resultado con isError: true, o sin structuredContent, muestra "Nada que mostrar".
• Informa que se vio una tarjeta. Cuando una tarjeta ha estado en pantalla el tiempo suficiente para leerse, el widget le indica a Matchai qué anuncios estuvieron visibles, durante cuánto tiempo y qué parte de cada uno, además del tipo general de plataforma del asistente (web, escritorio o móvil). Si el resultado no incluye un token para este informe, no se envía nada. Nunca envía texto de la conversación ni un identificador de usuario.

Un asistente que no renderiza MCP Apps ignora el widget. El texto de content y los datos de structuredContent contienen la respuesta completa. Si creas tus propias tarjetas, enlaza cada una a la url del anuncio.