Conexiones y herramientas de MCP

Sheet Best tiene un endpoint de cuenta para el uso habitual y un endpoint directo opcional para cada conexión.

URL de los endpoints

Alcance	Patrón de URL desplegada
Cuenta	`https://mcp.sheetbest.com/`
Conexión directa	`https://mcp.sheetbest.com/connections/<connection_id>`

Usa el endpoint de cuenta que aparece en tu perfil y las URL de conexión devueltas por Sheet Best. Así evitas mezclar los entornos de pruebas y producción.

Las herramientas de gestión de conexiones devuelven dos enlaces útiles para cada conexión:

directMcpUrl: servidor MCP remoto opcional centrado en esta conexión;
apiUrl: usa esta URL para llamar a la misma conexión mediante la API REST de Sheet Best.

Cómo funciona el contexto de conexión

El endpoint de cuenta expone herramientas de gestión de conexiones y todas las herramientas de hoja de la primera versión. Cada llamada a una herramienta de hoja en ese endpoint requiere:

{
  "connection_id": "YOUR_CONNECTION_UUID"
}

Obtén el UUID con sheetbest_list_connections. Cuando uses un endpoint directo, omite connection_id; la URL ya proporciona ese contexto. Los ejemplos siguientes muestran argumentos del endpoint de cuenta.

MCP Inspector con las herramientas de conexión y hoja expuestas por el endpoint MCP principal de Sheet Best.

Herramientas de cuenta

Las herramientas de cuenta gestionan tu catálogo de conexiones. No consumen solicitudes mensuales de API.

Herramienta	Función
`sheetbest_list_connections`	Lista tus conexiones, con su estado, métodos, URL de API y URL MCP directa opcional.
`sheetbest_create_connection`	Crea una conexión a partir de una URL nativa de Google Sheets y devuelve sus URL de API y MCP directa.

Listar conexiones

sheetbest_list_connections acepta:

{
  "include_archived": false,
  "include_mcp_disabled": true
}

Ambos campos son opcionales. Las conexiones archivadas se omiten de forma predeterminada; las conexiones con MCP desactivado se incluyen para que puedas entender por qué un endpoint no está disponible.

Crear una conexión

Llama a sheetbest_create_connection con:

{
  "url": "https://docs.google.com/spreadsheets/d/YOUR_TEST_SHEET_ID/edit",
  "name": "Inventory example",
  "mcp_enabled": true
}

Solo url es obligatorio. name usa el título o ID de la hoja de forma predeterminada y mcp_enabled usa true. La creación comprueba tu límite de conexiones, el acceso a Google Sheets y la fila de cabecera.

Herramientas de hoja

Un endpoint directo anuncia únicamente las herramientas permitidas por la configuración de su conexión y el plan. El endpoint de cuenta anuncia el catálogo completo de la primera versión; cada llamada sigue comprobando los métodos, el plan, el acceso de Google y la cuota de la conexión seleccionada.

Herramienta	Requisito	Consume cuota si tiene éxito	Modifica datos
`sheetbest_list_rows`	`GET` activado	Sí	No
`sheetbest_query_rows`	`GET` activado	Sí	No
`sheetbest_get_info`	`GET` activado y un plan con acceso a consultas avanzadas	Sí	No
`sheetbest_get_limits`	Ninguno	No	No
`sheetbest_get_permissions`	Ninguno	No	No
`sheetbest_add_rows`	`POST` activado	Sí	Sí
`sheetbest_update_rows`	`PATCH` o `PUT` activado	Sí	Sí
`sheetbest_delete_rows`	`DELETE` activado	Sí	Sí

sheetbest_aggregate y sheetbest_pivot no están disponibles mediante MCP.

Configuración de métodos de una conexión con las operaciones de lectura y escritura permitidas por Sheet Best.

Por qué puede faltar una herramienta

Si una herramienta no aparece en la lista de tu cliente:

Comprueba Advanced Settings → Methods (Configuración avanzada → Métodos) en la conexión.
Confirma que tu plan admita la operación. sheetbest_get_info requiere acceso a consultas avanzadas.
Si usas un endpoint directo, confirma que la conexión permita esa herramienta.
Reconecta o actualiza el servidor para que el cliente solicite la lista de herramientas actualizada.

El acceso de edición de Google determina si una escritura se completa. Los métodos permitidos determinan si se anuncia la herramienta de escritura.

Pestañas

La mayoría de las herramientas de filas aceptan un argumento tab opcional:

{
  "connection_id": "YOUR_CONNECTION_UUID",
  "tab": "Inventory",
  "limit": 25
}

Omite tab para usar la primera pestaña. Para cualquier otra, usa su título exacto.

Usa siempre la misma forma

Para lecturas y escrituras relacionadas en la primera pestaña, omite siempre tab o envía siempre su nombre. Las dos formas usan rutas de caché temporales diferentes.

Los mismos conceptos están disponibles en la API REST. Consulta trabajar con pestañas.

Leer y consultar filas

Listar filas

sheetbest_list_rows admite paginación, valores nativos y filtros de columna:

{
  "connection_id": "YOUR_CONNECTION_UUID",
  "limit": 25,
  "offset": 0,
  "raw": false,
  "search_ci": true,
  "columns": {
    "Status": "Open",
    "Owner": "*Taylor*"
  }
}

limit usa 100 de forma predeterminada y acepta valores de 1 a 1000.
offset usa 0 de forma predeterminada y empieza a contar desde cero.
columns busca valores exactos o patrones con el comodín *.
search_ci hace que las coincidencias de columna no distingan mayúsculas y minúsculas.
raw solicita valores nativos de las celdas cuando están disponibles.

El resultado incluye rows, totalRows, totalColumns, limit y offset. Consulta las guías REST de filtrado y paginación.

Consultar filas

sheetbest_query_rows compara valores de columna. Cada valor de consulta empieza por un operador:

Operador	Significado
`__eq`	Igual
`__ne`	Distinto
`__gt`	Mayor que
`__gte`	Mayor o igual que
`__lt`	Menor que
`__lte`	Menor o igual que

{
  "connection_id": "YOUR_CONNECTION_UUID",
  "query": {
    "Age": "__gte18",
    "Status": "__neArchived"
  },
  "limit": 100,
  "offset": 0
}

query es obligatorio. Deben cumplirse todas las condiciones. Consulta consultar datos para los conceptos REST correspondientes.

Añadir filas

sheetbest_add_rows acepta un objeto o un array no vacío. Las claves deben coincidir con las cabeceras de la hoja.

{
  "connection_id": "YOUR_CONNECTION_UUID",
  "data": [
    {
      "Item": "Keyboard",
      "Status": "New"
    },
    {
      "Item": "Mouse",
      "Status": "New"
    }
  ]
}

Esto modifica tu hoja

Revisa la conexión, la pestaña y los valores de destino antes de aprobar la llamada. Una llamada correcta cuenta como una solicitud de API.

Consulta añadir filas para la operación REST equivalente.

Actualizar filas

sheetbest_update_rows requiere data y exactamente un selector:

index: un índice de fila que empieza en cero o una expresión de índices;
columns: una o varias coincidencias de columna.

De forma predeterminada, la herramienta realiza una actualización parcial como PATCH:

{
  "connection_id": "YOUR_CONNECTION_UUID",
  "columns": {
    "Item": "Keyboard"
  },
  "data": {
    "Status": "Active"
  },
  "put": false
}

Establece put en true para sustituir las filas coincidentes como con PUT. La sustitución vacía las columnas no proporcionadas:

{
  "connection_id": "YOUR_CONNECTION_UUID",
  "index": "2",
  "data": {
    "Item": "Keyboard",
    "Status": "Archived"
  },
  "put": true
}

Confirma si quieres actualizar o sustituir

Usa put: false salvo que quieras sustituir toda la fila coincidente. Confirma el selector y los datos antes de aprobar cualquiera de las operaciones.

La conexión debe permitir PATCH para una actualización parcial o PUT para una sustitución. Consulta actualizar filas.

Eliminar filas

sheetbest_delete_rows también requiere exactamente un selector:

{
  "connection_id": "YOUR_CONNECTION_UUID",
  "columns": {
    "Status": "Delete me"
  }
}

{
  "connection_id": "YOUR_CONNECTION_UUID",
  "index": "2"
}

La eliminación es permanente

La herramienta elimina todas las filas coincidentes. Pide al asistente que primero liste o cuente las coincidencias y aprueba la eliminación solo cuando el selector sea correcto.

Consulta eliminar filas para la operación REST equivalente.

Comprobar permisos

sheetbest_get_permissions no modifica la hoja ni consume cuota. Distingue tres tipos de acceso:

{
  "google": {
    "isValid": true,
    "isPrivate": false,
    "isEditable": true,
    "hasHeaders": true
  },
  "sheetbest": {
    "allowedMethods": ["GET", "PATCH", "POST"],
    "mcpEnabled": true
  },
  "effective": {
    "readRows": true,
    "addRows": true,
    "updateRows": true,
    "deleteRows": false
  }
}

google indica si la hoja es accesible, privada, editable y tiene cabeceras válidas.
sheetbest indica los métodos configurados y el estado de MCP de la conexión.
effective indica qué puede hacer actualmente la conexión MCP al combinar esas comprobaciones.

Si el acceso efectivo es inferior al esperado, consulta solución de problemas de MCP.

Consultar la cuota

sheetbest_get_limits devuelve limit, remaining y plan sin consumir cuota. Las llamadas correctas sobre filas y sheetbest_get_info cuentan una vez. Las comprobaciones previas o las operaciones fallidas no cuentan como solicitudes correctas.

Próximo paso

Aprende a proteger y gestionar tu token MCP.

URL de los endpoints​

Cómo funciona el contexto de conexión​

Herramientas de cuenta​

Listar conexiones​

Crear una conexión​

Herramientas de hoja​

Por qué puede faltar una herramienta​

Pestañas​

Leer y consultar filas​

Listar filas​

Consultar filas​

Añadir filas​

Actualizar filas​

Eliminar filas​

Comprobar permisos​

Consultar la cuota​

Próximo paso​