Servidor MCP

¿Qué es el servidor MCP de Bidlo?

El servidor Bidlo MCP es un servidor Model Context Protocol en https://app.bidlo.ai/api/mcp que permite a un agente leer los datos de un equipo de Bidlo y, con una clave que pueda editar datos, cambiarlos. Cada herramienta es una operación de la REST API, con las mismas entradas, respuestas y errores. El nombre del servidor es bidlo-mcp. La clave identifica al equipo, así que ninguna herramienta acepta un argumento de equipo. Consultar datos explica las colecciones, los campos y los filtros que ambos comparten.

¿Cómo conecto un cliente?

Apunta el cliente a https://app.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.

Settings → Features → MCP crea una clave de solo lectura con la etiqueta Bidlo MCP e imprime debajo una configuración ya lista. Para una clave que pueda editar datos, crea una en Settings → Features → API. Acceso y claves detalla el resto.

Usa https://app.bidlo.ai/api/mcp tal cual. El host anterior lite.bidlo.ai redirige ahí, y los clientes sueltan el encabezado Authorization cuando siguen una redirección a otro host, así que una llamada mandada ahí regresa 401.

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=eyJ1cmwiOiJodHRwczovL2FwcC5iaWRsby5haS9hcGkvbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIFlPVVJfQVBJX0tFWSJ9fQ==

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://app.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://app.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://app.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": "me", "arguments": {} }
  }'

No hay intercambio OAuth ni nada que registrar. Las rutas de descubrimiento que un cliente consulta responden 404 a propósito, para que el cliente pase a usar la clave que recibió.

¿Qué herramientas puede llamar un cliente?

El cliente solo ve las herramientas que permite su clave: 12 herramientas de lectura con Leer datos, 15 de escritura de datos con Editar datos y 7 de colecciones y campos con Editar colecciones y campos. Cada herramienta es una operación REST con guiones bajos en el nombre y acepta las mismas entradas: las partes de la ruta se convierten en argumentos junto al cuerpo.

Herramientas de lectura

La clave necesita Read data. Estas llevan readOnlyHint, así que un cliente puede correrlas sin preguntar.

Herramientas de escritura

La clave necesita Editar datos. Leer datos no es necesario para las herramientas de escritura. documents_trash lleva destructiveHint, así que un cliente cuidadoso pregunta antes de correrla.

Herramientas de colecciones y campos

La clave necesita Editar colecciones y campos (schema:write). Acceso completo lo incluye; Leer y escribir datos no. Una clave Personalizada puede tener solo data:write o solo schema:write; solo ve ese grupo y no puede llamar a me. El rol actual del creador sigue limitando cada herramienta.

Qué herramientas ve una clave

Llamar a una herramienta a la que la clave no tiene acceso falla con Tool <name> not found. Una clave creada en Settings → Features → MCP, o sin creador guardado, es de solo lectura, y una clave pierde sus herramientas de escritura cuando el rol de quien la creó deja de permitir editar. Llama a me para ver qué puede hacer una clave ahora.

Entradas de las herramientas

collection_id acepta el id o el nombre de una colección, y un campo acepta su id o un nombre que no comparta con otro campo. Un argumento que la herramienta no acepta, como team_id, hace fallar la llamada. La definición de cada herramienta está en /openapi.json.

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 documents_query hasta que lo estén.

¿Cómo encuentro y leo datos?

Lista las colecciones, lee los campos de la que te interesa, luego consúltala. En los ejemplos, los signos de menor y mayor que señalan un valor que debes buscar, y Name, Bid Date y County son nombres de campo de ejemplo; lee los tuyos en fields_list.

me

No acepta argumentos y devuelve los permisos de la clave, su límite de colecciones y su vencimiento. Acceso y claves muestra la respuesta.

collections_list

No lleva argumentos y lista las colecciones que esta clave puede leer, con sus ids.

fields_list

Lista los campos de una colección: el id, el nombre que le dio tu equipo y su tipo. reference_id nombra la colección a la que apunta una relación.

{ "collection_id": "<collection_id>" }

{
  "data": [
    {
      "id": "<field_id>",
      "name": "Bid Date",
      "field_type": "date",
      "primary_key": false,
      "reference_id": null,
      "description": "…"
    }
  ]
}

documents_query

Lee una página de documentos. Los campos, filtros y órdenes identifican un campo por id o por nombre, con un filtro por campo. Consultar datos lista los operadores que acepta cada tipo de campo. documents_list acepta los mismos argumentos.

{
  "collection_id": "<collection_id>",
  "fields": ["Name", "Bid Date", "County"],
  "filters": [
    {
      "field_id": "Bid Date",
      "operator": "between",
      "value": { "start": "2026-10-01", "end": "2026-12-31" }
    }
  ],
  "sorts": [{ "field_id": "Bid Date", "direction": "asc" }],
  "limit": 100
}

{
  "data": [
    {
      "id": "<document_id>",
      "name": "…",
      "collection_id": "<collection_id>",
      "created_at": "…",
      "updated_at": "…",
      "fields": {
        "<field_id>": {
          "value": "…",
          "field_name": "Bid Date",
          "field_type": "date",
          "field_id": "<field_id>",
          "field_value_id": "<field_value_id>"
        }
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 100,
    "collection_id": "<collection_id>",
    "groupPagination": "…",
    "next_cursor": "<next_cursor>"
  }
}

Los valores regresan en fields, identificados por id de campo, cada uno con el nombre y el tipo de su campo.

La página siguiente

Envía meta.next_cursor de vuelta como cursor, con la misma consulta, hasta que regrese null. Consultar datos explica la paginación y la agrupación.

El servidor incluye esta receta como el prompt query-bidlo-data, y el recurso bidlo://collections contiene lo que collections_list devuelve.

¿Cómo cambio datos?

Llama a la herramienta de escritura que corresponda al cambio con una clave que pueda editar datos, y corre un upsert con dry_run en true antes de correrlo de verdad.

documents_upsert

Busca cada fila por 1 a 3 campos, actualiza los documentos que coinciden y agrega el resto. name es el campo de título del documento, y fields lleva los demás por id o nombre. update_mode es overwrite o fill_empty, que no toca un valor que ya existe. Con dry_run en true reporta lo que haría y no escribe nada.

{
  "collection_id": "<collection_id>",
  "match_fields": ["Name"],
  "rows": [
    {
      "name": "<name>",
      "fields": { "Bid Date": "2026-11-12", "County": ["<document_id>"] }
    }
  ],
  "dry_run": true,
  "update_mode": "fill_empty"
}

{
  "data": {
  "success": true,
  "dry_run": true,
  "created": <number>,
  "updated": <number>,
  "…": "…",
  "errors": []
  }
}

Una fila que coincide con más de un documento se lista en data.errors como ambiguous_match. REST API detalla las reglas de coincidencia y lo que rechaza una escritura.

Reintentar una escritura

Envía un nuevo encabezado Idempotency-Key en la solicitud MCP de cada escritura, nunca en los encabezados fijos de la configuración de un cliente. REST API explica cómo un reintento devuelve la respuesta guardada.

¿Cómo se reportan los errores?

Una herramienta que falla devuelve un resultado marcado con isError cuyo texto es el cuerpo JSON del error, y una clave que el servidor rechaza hace fallar toda la solicitud HTTP con un error JSON-RPC.

{
  "content": [
    {
      "type": "text",
      "text": "{ \"error\": { \"code\": \"validation\", \"message\": \"Unknown field\", \"details\": … }, \"request_id\": \"<request_id>\" }"
    }
  ],
  "isError": true
}

El cuerpo del error es el de la REST API. REST API lista todos los códigos.

¿Cuáles son los límites?

Una consulta devuelve de 1 a 500 documentos por página, 100 por defecto, y cada clave tiene 600 lecturas y 120 escrituras por minuto.

Un resultado de herramienta no lleva encabezado Retry-After, así que si pasas el límite espera al siguiente minuto. REST API detalla todos los demás límites.