--- title: "Servidor MCP" description: "Conecta un asistente de IA al servidor MCP de Matchai y busca anuncios. Endpoints, transporte, límites y configuración para Claude, ChatGPT y otros clientes." last_updated: "2026-10-21" lang: "es" canonical: "https://matchai.co/docs/es/developers/mcp-server" --- # Servidor MCP > Conecta un asistente de IA al servidor MCP de Matchai y busca anuncios. Endpoints, transporte, límites y configuración para Claude, ChatGPT y otros clientes. Source: https://matchai.co/docs/es/developers/mcp-server El servidor MCP de Matchai permite que un asistente de IA busque los anuncios que los profesionales inmobiliarios han publicado en Matchai, abra un anuncio y consulte a un corredor. MCP, el Model Context Protocol, es el estándar abierto que usan los asistentes para llamar a herramientas externas. El servidor es público y de solo lectura. No necesita cuenta, clave de API ni inicio de sesión, y solo devuelve datos publicados. ## Endpoints [#endpoints] | URL | Úsala para | |---|---| | `https://matchai.co/mcp` | El endpoint predeterminado. Úsalo para ChatGPT, Claude Code, el MCP Inspector, scripts y cualquier otro cliente. | | `https://matchai.co/mcp/claude` | El mismo servidor, para las apps de Claude, de modo que las tarjetas de anuncios se muestren dentro de la conversación. | | `https://matchai.co/mcp/server-card` | Una descripción JSON del servidor para directorios y escáneres. | Ambas URL ejecutan el mismo servidor y devuelven las mismas herramientas y los mismos datos. Solo difieren en un ajuste del widget, y los dos asistentes no coinciden en ese ajuste: ChatGPT quiere que se declare un dominio dedicado para el widget, y Claude no muestra un widget cuyo dominio declarado no coincida con su propia URL de conector. Con dos URL, cada asistente obtiene lo que necesita. ## Transporte [#transport] El servidor habla MCP sobre Streamable HTTP, en su forma sin estado, con mensajes JSON-RPC 2.0. - **POST:** envía un único mensaje JSON-RPC al endpoint. Una solicitud recibe `200` con un cuerpo `application/json`. Una notificación recibe `202` sin cuerpo. - **Sin sesiones.** El servidor no emite ningún `Mcp-Session-Id` y no recuerda nada entre solicitudes, así que cada solicitud puede responderse por sí sola. Sigue de todos modos el handshake estándar, para que tu cliente también funcione con otros servidores. - **Sin flujo de eventos.** `GET` y `DELETE` responden `405`, que es la respuesta correcta para un servidor que no tiene nada que enviar por iniciativa propia. `OPTIONS` responde `204` para CORS. - **Sin lotes.** Envía un mensaje por solicitud. Un array se rechaza con `-32600`. - **Versiones del protocolo:** `2025-11-25`, `2025-06-18` y `2025-03-26`. `initialize` devuelve tu versión cuando el servidor la habla, y la más reciente en caso contrario. Si envías un encabezado `MCP-Protocol-Version` después de `initialize`, debe ser una de estas, o la solicitud falla con `400`. - **Tamaño.** El cuerpo de una solicitud puede tener hasta 256 KB. El servidor responde a estos métodos: | Método | Respuesta | |---|---| | `initialize` | Versión del protocolo, capacidades (`tools` y `resources`), `serverInfo` e instrucciones de uso para el modelo. Requiere `params.protocolVersion`. | | `ping` | Un resultado vacío. | | `tools/list` | Las tres [herramientas públicas](https://matchai.co/docs/es/developers/mcp-server/public-tools), con sus esquemas de entrada y de salida. | | `tools/call` | Ejecuta una herramienta. | | `resources/list` | Un recurso: el widget de tarjetas de anuncios. | | `resources/templates/list` | Una lista vacía. | | `resources/read` | El documento del widget de tarjetas de anuncios. | | `notifications/initialized`, `notifications/cancelled` | Se aceptan con `202`. | Cualquier otro método responde `-32601` (método no encontrado). El servidor no ofrece las funciones de prompts, registro ni autocompletado. `serverInfo.name` es `matchai-listings` y `serverInfo.version` es una versión semántica. Cambia cuando se agrega una herramienta o un campo, o cuando cambia su estructura. ## Acceso, datos y límites [#access-data-and-limits] - **Autenticación.** Ninguna. `/.well-known/mcp.json` declara `authentication.required: false`, y el servidor no pide ninguna clave, token ni inicio de sesión. - **Datos.** Los anuncios publicados, y el perfil público de los corredores que han publicado un sitio, una Página Matchai o una tarjeta de presentación. El número de teléfono y la dirección de correo electrónico de un corredor aparecen solo cuando están publicados en esa tarjeta de presentación. - **Orden de los resultados.** Por relevancia para la solicitud y por la fecha de la última actualización del anuncio. Ningún corredor puede pagar para cambiar el orden ni para aparecer. - **Límite de solicitudes.** Cada dirección de origen puede hacer 600 solicitudes `tools/call` por minuto. Por encima de eso, la llamada devuelve un resultado de herramienta con `isError: true` y un mensaje que pide volver a intentarlo en un minuto. El límite se aplica solo a `tools/call`. Es una protección contra abusos, fijada lo bastante alta como para que un host de asistentes con mucho tráfico no la alcance. - **CORS.** Abierto a todos los orígenes, así que funcionan las herramientas basadas en navegador como el MCP Inspector. El servidor no lee ninguna cookie ni credencial. Las respuestas preflight pueden almacenarse en caché durante 24 horas. - **Caché.** Las respuestas se envían con `Cache-Control: no-store`. ## Documentos de descubrimiento [#discovery-documents] Matchai publica descripciones del servidor legibles por máquina. Todas son JSON, envían un `ETag`, respetan `If-None-Match` y permiten lecturas de origen cruzado. | URL | Qué es | |---|---| | `https://matchai.co/mcp/server-card` | La tarjeta del servidor MCP (server card): nombre `co.matchai/listings`, versión, descripción, endpoint y versiones del protocolo compatibles. También se sirve en `/.well-known/mcp/server-card.json`. | | `https://matchai.co/.well-known/mcp.json` | Una descripción más completa: ambos endpoints, `authentication.required: false`, las herramientas con sus anotaciones y el recurso del widget. | | `https://matchai.co/.well-known/ai-catalog.json` | Un catálogo a nivel de dominio que apunta a la tarjeta del servidor, al documento OpenAPI del host y a su `llms.txt`. | | `https://matchai.co/.well-known/api-catalog` | Un catálogo de API según la RFC 9727 que enumera los endpoints públicos. | | `https://matchai.co/openapi.json` | Un documento OpenAPI 3.1 para los endpoints públicos. | Los sitios de los corredores y las Páginas Matchai sirven sus propias copias de estos documentos. Apuntan al mismo servidor MCP en `matchai.co`. ## Conectar un asistente [#connect-an-assistant] Que puedas agregar un conector personalizado depende de tu plan y, en un espacio de trabajo de equipo, de tu administrador. Los nombres de los menús pueden cambiar entre versiones de la app. ### Claude [#claude] Abre Claude y ve a **Configuración → Conectores**, y luego elige **Agregar conector personalizado**. Escribe el nombre `Matchai` y la URL del servidor `https://matchai.co/mcp/claude`. Deja vacías las opciones de autenticación. El servidor no necesita inicio de sesión. Guarda el conector, inicia una nueva conversación y pide algo concreto, como "Encuentra un condominio de 3 habitaciones en venta en Laval por menos de $600 000". Claude llama a `search_listings` y muestra los resultados como tarjetas de anuncios. Para agregar el servidor a Claude Code desde una terminal: ```bash claude mcp add --transport http matchai https://matchai.co/mcp ``` ### ChatGPT [#chatgpt] Abre ChatGPT y ve a **Configuración → Aplicaciones y conectores → Configuración avanzada**, y luego activa el modo de desarrollador. Elige **Crear** para agregar un conector. Escribe el nombre `Matchai` y la URL del servidor `https://matchai.co/mcp`, y elige que no haya autenticación. Guárdalo, activa el conector en un chat nuevo y pide anuncios con tus propias palabras. ### Otros clientes [#other-clients] La mayoría de los clientes compatibles con servidores MCP remotos aceptan una URL en un archivo de configuración: ```json title="mcp.json" { "mcpServers": { "matchai": { "url": "https://matchai.co/mcp" } } } ``` Los clientes que piden un tipo de transporte deben usar Streamable HTTP, sin autenticación. ## Llamar al servidor desde tu propio código [#call-the-server-from-your-own-code] Los ejemplos usan `curl`. Cada solicitud es un único mensaje JSON-RPC. **Inicializa.** Envía `initialize` con la versión del protocolo que quieras. ```bash curl -s https://matchai.co/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": { "name": "my-client", "version": "0.1.0" } } }' ``` Una respuesta abreviada: ```json { "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-11-25", "capabilities": { "tools": {}, "resources": {} }, "serverInfo": { "name": "matchai-listings", "title": "Matchai", "version": "1.0.0", "websiteUrl": "https://matchai.co" }, "instructions": "Matchai is a real estate platform where licensed brokers in Québec and across Canada publish their listings. …" } } ``` **Confirma.** Envía la notificación `initialized`. El servidor responde `202` sin cuerpo. ```bash curl -s -i https://matchai.co/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "notifications/initialized" }' ``` **Lista las herramientas.** ```bash curl -s https://matchai.co/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }' ``` El resultado tiene un array `tools` con `search_listings`, `get_listing` y `get_professional`. Cada entrada incluye un `name`, un `title`, una `description`, un `inputSchema`, un `outputSchema` y unas `annotations` que marcan la herramienta como de solo lectura. **Llama a una herramienta.** ```bash curl -s https://matchai.co/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "search_listings", "arguments": { "query": "3 bedroom condo in Laval under 600k", "limit": 3 } } }' ``` ```js async function rpc(method, params, id = 1) { const response = await fetch('https://matchai.co/mcp', { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream', }, body: JSON.stringify({ jsonrpc: '2.0', id, method, params }), }); return response.json(); } const { result } = await rpc('tools/call', { name: 'search_listings', arguments: { query: '3 bedroom condo in Laval under 600k', limit: 3 }, }); if (result.isError) throw new Error(result.content[0].text); for (const listing of result.structuredContent.listings) { console.log(`${listing.title} - ${listing.priceText} - ${listing.url}`); } ``` El resultado contiene texto legible en `content`, datos tipados en `structuredContent` y un objeto `_meta` para el widget de tarjetas de anuncios. Consulta las [herramientas públicas](https://matchai.co/docs/es/developers/mcp-server/public-tools) para ver la estructura de cada uno. ## Errores [#errors] Los problemas con el mensaje en sí son errores JSON-RPC. Los problemas que un modelo puede corregir, como un argumento incorrecto o una URL que no coincide con ningún anuncio, vuelven como un resultado de herramienta con `isError: true` y un mensaje que el modelo puede leer. | Situación | Respuesta | |---|---| | El cuerpo no es JSON válido | HTTP `400`, error `-32700` | | No es un mensaje JSON-RPC 2.0, es un lote o no tiene método | HTTP `400`, error `-32600` | | El cuerpo supera los 256 KB | HTTP `413`, error `-32600` | | Encabezado `MCP-Protocol-Version` no compatible | HTTP `400`, error `-32600` | | Método desconocido | HTTP `200`, error `-32601` | | Parámetros faltantes o no válidos, o un nombre de herramienta desconocido | HTTP `200`, error `-32602` | | `resources/read` para un URI que el servidor no tiene | HTTP `200`, error `-32002` | | `GET` o `DELETE` | HTTP `405`, con `Allow: POST, OPTIONS` | | Un argumento de herramienta que no pasa la validación | HTTP `200`, resultado con `isError: true` | | Nada coincide con una consulta de `get_listing` o `get_professional` | HTTP `200`, resultado con `isError: true` | | Se superó el límite de solicitudes, o hubo un fallo temporal | HTTP `200`, resultado con `isError: true`. Vuelve a intentarlo en breve. | Entradas, salidas y ejemplos de cada herramienta, y el widget de tarjetas de anuncios. La misma búsqueda como un endpoint HTTP simple, sin MCP. Cómo cada sitio de Matchai se describe ante los asistentes de IA. ## Sitemap - [Todas las páginas de la documentación de Matchai](https://matchai.co/docs/sitemap.md) - [llms.txt](https://matchai.co/docs/es/llms.txt)