Servidor MCP

¿Qué es el servidor MCP de Bidlo?

El servidor MCP de Bidlo es un servidor Model Context Protocol de solo lectura en https://lite.bidlo.ai/api/mcp que le da a un agente cinco herramientas para leer las obras, las partidas, los contratistas y las plantas de un equipo de Bidlo. Son los mismos datos que tu equipo ve en la app, leídos por un agente y no por una persona.

El servidor ofrece cinco herramientas, dos recursos y un prompt, y ninguna herramienta de escritura. Su nombre es bidlo-mcp. Una sola clave sostiene toda la conexión: la clave identifica al equipo, así que ninguna herramienta lleva un parámetro de equipo y no hay nada más que configurar. La misma clave lee la REST API, and Consultar datos describe las colecciones, los campos y los filtros que comparten las dos vías.

¿Cómo conecto un cliente?

Apunta el cliente a https://lite.bidlo.ai/api/mcp y manda tu clave de API en un encabezado Authorization; las tres configuraciones de abajo son esa misma conexión en las tres formas que piden los clientes.

Se necesita una cuenta de Bidlo. Cualquiera puede conseguir una agendando una llamada en https://cal.com/matt-wolfe-yecrho/30min — Bidlo prepara el equipo, y luego un dueño o administrador del equipo crea la clave de API en Settings → Features → API. No hay un plan público ni se puede abrir una cuenta por cuenta propia.

Settings → Features → MCP crea la misma clave con la etiqueta Bidlo MCP con acceso de lectura y muestra debajo una configuración lista. Acceso y claves cubre cómo crear una, rotarla y revocarla.

Cursor

Cursor se instala con un enlace directo. La configuración que lleva el enlace está en base64, así que vuelve a codificarla con una clave real en lugar de YOUR_API_KEY en vez de editar el texto.

cursor://anysphere.cursor-deeplink/mcp/install?name=bidlo&config=eyJ1cmwiOiJodHRwczovL2xpdGUuYmlkbG8uYWkvYXBpL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciBZT1VSX0FQSV9LRVkifX0=

HTTP con transmisión continua

Un cliente que habla streamable HTTP toma la URL y el encabezado directamente. Claude Code y Cursor lo hacen.

{
  "url": "https://lite.bidlo.ai/api/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  }
}

mcp-remote

Un cliente que solo habla stdio corre el mcp-remote como adaptador sobre npx, que mantiene la conexión HTTP por él. Este es el bloque que imprime la propia página de MCP en la app.

{
  "mcpServers": {
    "bidlo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://lite.bidlo.ai/api/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

¿Cómo funciona el transporte?

El servidor habla HTTP con transmisión continua y no guarda estado, así que cada solicitud lleva la clave y todo lo demás que necesita, y un POST se responde con un solo cuerpo JSON.

curl -X POST https://lite.bidlo.ai/api/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "get_team_collections", "arguments": {} }
  }'

Sin estado quiere decir justo eso. No se emite ningún id de sesión, cada solicitud la responde un servidor nuevo y nada de lo que fijes en una solicitud pasa a la siguiente, así que manda la clave y los argumentos completos cada vez. Las versiones de protocolo de 2024-11-05 to 2025-11-25 se aceptan en el encabezado Mcp-Protocol-Version ; una versión que el servidor no conoce es un 400.

No hay intercambio OAuth ni nada que dar de alta. Las rutas de descubrimiento que un cliente prueba bajo el servidor responden 404 a propósito, así que el cliente pasa a usar el token bearer que recibió. Las respuestas llevan Access-Control-Allow-Origin: *, and authorization, content-type, mcp-session-id, mcp-protocol-version and last-event-id son los encabezados permitidos en la solicitud.

¿Qué herramientas puede llamar un cliente?

Hay cinco herramientas, todas de solo lectura, y cada una responde con un solo bloque de texto con JSON con formato. En las formas de abajo, un nombre entre corchetes angulares representa un valor que te toca buscar y los puntos suspensivos representan un valor que se omitió.

get_team_collections

Lista las colecciones que esta clave puede leer. No recibe argumentos. La clave identifica al equipo, así que no hay nada que acotar ni un parámetro de equipo en esta ni en ninguna otra herramienta.

{
  "collections": [
    {
      "collection_id": "<collection_id>",
      "name": "Project",
      "description": "…",
      "mutable": true
    }
  ]
}

Las colecciones regresan ordenadas por nombre. mutable dice si tu equipo puede editar la colección en la app; no tiene efecto en este servidor, que nunca escribe.

Nada de esto falla por sí solo. Una clave ausente o mala es el 401 en la sección de errores de abajo.

get_collection_fields

Lista los campos de una o más colecciones, con los operadores que acepta cada campo. Dale ids de colección, no nombres. Lee los ids en get_team_collections primero; se usan los primeros 20 ids de la lista y el resto se descarta.

{
  "collections": [
    {
      "collection_id": "<collection_id>",
      "collection_name": "Project",
      "field_count": <number>,
      "fields": [
        {
          "field_id": "<field_id>",
          "name": "Bid Date",
          "field_type": "date",
          "filter_field_type": "date",
          "primary_key": false,
          "reference_collection_id": null,
          "description": "…",
          "aka": ["…"]
        }
      ]
    }
  ],
  "unknown_collection_ids": [],
  "operators_by_filter_field_type": { "date": ["eq", "gt", "lt", "between", "…"] },
  "filter_value_shapes": { "date_between": { "start": "ISO date string", "end": "ISO date string" } },
  "formula_expression_syntax": "…"
}

{
  "collection_ids": ["<collection_id>", "<collection_id>"]
}

field_id es como la app distingue dos campos, y es lo que nombra un filtro REST. name es como tu equipo llama al campo: un campo que viene de fábrica se puede renombrar, así que dos equipos pueden tener nombres distintos para el mismo campo, y por eso en esta página no se imprime ningún id ni ningún nombre de campo como si fuera un hecho. filter_field_type es el tipo con el que se filtra el campo, y es la clave con la que está escrita la tabla de operadores. reference_collection_id nombra la colección a la que apunta una relación, que es la colección donde buscar con resolve_documents_by_name. La respuesta también repite los operadores y los formatos de valor, así que un cliente puede leerlos en el momento en vez de cargar una copia.

Un id de colección que no es de tu equipo regresa en unknown_collection_ids en vez de fallar la llamada. Una colección con todos los campos ocultos falla con Collection has no visible fields.

resolve_documents_by_name

Convierte un nombre en el id que necesita un filtro. Un filtro sobre un contratista, un condado o una agencia quiere el id del documento, no su nombre. Esta herramienta busca por nombre en una colección y devuelve los ids.

{
  "collection_id": "<collection_id>",
  "collection_name": "Counties",
  "lookups": [
    {
      "input": "Travis County",
      "exactMatches": [
        { "id": "<document_id>", "name": "Travis County", "document_mention": "…" }
      ],
      "candidates": [],
      "unresolved": false
    }
  ],
  "unresolved_names": [],
  "summary": "…"
}

{
  "collection_id": "<collection_id>",
  "names": ["Travis County", "Bexar County"],
  "limit": 10
}

Una coincidencia exacta es aquella cuyo nombre coincide después de normalizar mayúsculas y espacios. Todo lo demás que regresó es un candidato, y un nombre que no coincidió con nada aparece en unresolved_names. document_mention es un enlace a la app de Bidlo, no una URL pública.

Manda uno de query or names, o la llamada falla con el mensaje Provide `query` or `names` for document lookup. Un id de colección que no es de tu equipo falla con Collection is not available for this team.

query_database_data

Lee una página de documentos: filtros, orden, un límite y una página. Esta es la herramienta que lee datos. Recibe una colección por nombre y referencias de campos por nombre, las filtra y las ordena, y devuelve una página de documentos.

{
  "collection_id": "<collection_id>",
  "collection_name": "Project",
  "page": 1,
  "query": null,
  "grouped": false,
  "selected_fields": [
    { "field_id": "<field_id>", "field_name": "Bid Date" }
  ],
  "documents": [
    {
      "document_id": "<document_id>",
      "document_name": "…",
      "document_mention": "…",
      "fields": {
        "Bid Date": "…",
        "County": { "id": "<document_id>", "name": "…", "document_mention": "…" },
        "Engineer's Estimate": "…"
      }
    }
  ],
  "returned_row_count": <number>,
  "has_more": true,
  "next_page": 2,
  "warnings": ["…"]
}

{
  "collection_name": "Project",
  "filters": [
    {
      "field_name": "Bid Date",
      "operator": "between",
      "value": { "start": "2026-10-01", "end": "2026-12-31" }
    },
    { "field_name": "County", "operator": "contains", "value": "Travis County" }
  ],
  "sorts": [{ "field_name": "Bid Date", "direction": "asc" }],
  "return_fields": ["Name", "Bid Date", "County", "Agency", "Engineer's Estimate"],
  "limit": 25,
  "page": 1
}

Los operadores son is_null, is_not_null, eq, ne, contains, not_contains, starts_with, ends_with, gt, lt, gte, lte, between, relative_range, within_distance, outside_distance. Cuáles acepta un campo dado dependen del tipo con el que se filtra, y Consultar datos tiene esa tabla junto con la forma de valor que pide cada uno. Hay cuatro comportamientos que conviene conocer antes de la primera llamada. Sin return_fields vuelve un conjunto predeterminado de hasta 8 campos con un aviso que lo dice, así que nombra los campos que quieres. Un segundo filtro en un campo que ya tiene uno lo reemplaza en vez de fallar, que es lo contrario de lo que hace REST en la REST API. Un valor de relación o de etiqueta dado como nombre se busca por ti, y un valor dado como id se usa tal cual. Y la respuesta no trae un conteo total: has_more and next_page son la forma de saber que hay otra página.

Una entrada que la validación rechaza hace fallar la llamada: un limit mayor que 100, un operador fuera de la lista de arriba, una dirección que no sea asc or desc. Una colección, un campo de retorno, un campo de filtro o un campo de orden que el servidor no encuentra no hace fallar la llamada; regresa como un resultado normal cuyo JSON lleva un error como clave, y el mensaje nombra la herramienta que sigue. Lo mismo pasa con un nombre ambiguo en un filtro de relación, que apunta a resolve_documents_by_name.

query_mentioned_document

Lee un documento por id. Úsala cuando ya tienes el id de un documento y quieres esa obra, ese contratista o esa planta completos en vez de una página de filas.

{
  "_document_id": "<document_id>",
  "_document_name": "…",
  "document_mention": "…",
  "_collection": "Project",
  "document_profile": "…",
  "Bid Date": "…",
  "County": { "id": "<document_id>", "name": "…", "document_mention": "…" },
  "Engineer's Estimate": "…",
  "omitted_fields": { "field_names": ["…"], "note": "…" }
}

{
  "document_id": "<document_id>",
  "fields_to_fetch": ["Name", "Bid Date", "Agency", "Low Bid"]
}

Los valores de los campos van en el nivel superior del objeto con sus propios nombres, así que el cliente los lee por nombre. Sin fields_to_fetch, los campos vacíos se descartan y regresan 40 campos como máximo; el resto se nombran en omitted_fields, y una segunda llamada que los nombre los carga.

Un id de documento que no es de tu equipo regresa como un resultado normal que lleva error y el mensaje Document <document_id> not found or access denied.

Próximamente. Vienen herramientas de mercado: search_projects, search_contractors, search_facilities, y precios unitarios comparables de una partida en un condado. Ninguna está disponible hoy. Arma las mismas consultas con query_database_data hasta que lo estén.

¿En qué orden conviene llamarlas?

Lista las colecciones, lee los campos de la que quieres, convierte los nombres a ids, luego consúltala, y lee un solo documento por id cuando necesites todo lo que tiene.

1. get_team_collections para las colecciones que esta clave puede leer, con sus ids.
2. get_collection_fields para los campos de la colección que quieres, con los nombres de campo por los que filtrar y la colección a la que apunta una relación.
3. resolve_documents_by_name para cualquier nombre escrito en palabras que vaya a ser valor de un filtro, como un condado o un contratista. Sáltala cuando ya tienes el id.
4. query_database_data para la página de obras, partidas o contratistas en sí.
5. query_mentioned_document cuando una de esas filas es la respuesta y quieres todo lo que trae.

El servidor trae esa receta como prompt, query-bidlo-data, así que un cliente puede cargarlo en vez de que se lo digan. Dos recursos ahorran una llamada en el primer paso.

¿Cómo se reportan los errores?

Por dos canales: la entrada que el servidor no puede aceptar hace fallar la llamada y se marca como error, y una solicitud que entendió pero no pudo responder regresa como un resultado normal cuyo JSON lleva una clave error.

El segundo canal es el que agarra desprevenidos a los clientes. Un resultado que no está marcado como error no es por fuerza una respuesta, así que lee el JSON del bloque de texto y busca un error como clave antes de leer las filas. Esos mensajes están escritos para actuar sobre ellos: cada uno nombra la herramienta que lo arregla.

¿Cuáles son los límites?

Una consulta devuelve como máximo 100 renglones por página y se detiene en la página 20, y los demás topes están en la tabla de abajo.

Ninguna respuesta trae un conteo total. Pagina hasta que has_more sea false, o filtra más fino.

¿A dónde voy después?

Lee Consultar datos para los operadores y las formas de valor que comparten las dos vías, lee la página REST API si quieres HTTP simple en vez de MCP, y escribe a support@bidlo.ai con lo que ninguna de las dos resuelva.

• Consultar datos. Las colecciones, los tipos de campo, los operadores que acepta cada uno y la forma de cada valor.
• REST API. Los mismos datos con GET and POST, para tres colecciones.
• Acceso y claves. Conseguir una clave, guardarla, rotarla.
• /openapi.json. La especificación legible por máquina.

Lo que estas no respondan, escribe a support@bidlo.ai.