Conexões e ferramentas do MCP

O Sheet Best tem um endpoint da conta para uso normal e um endpoint direto opcional para cada conexão.

URLs dos endpoints

Escopo	Padrão de URL implantada
Conta	`https://mcp.sheetbest.com/`
Conexão direta	`https://mcp.sheetbest.com/connections/<connection_id>`

Use o endpoint da conta exibido no perfil e as URLs de conexão retornadas pelo Sheet Best. Isso evita misturar os ambientes de homologação e produção.

As ferramentas de gerenciamento de conexões retornam dois links úteis para cada conexão:

directMcpUrl: servidor MCP remoto opcional focado nesta conexão;
apiUrl: use esta URL para chamar a mesma conexão pela API REST do Sheet Best.

Como funciona o contexto da conexão

O endpoint da conta expõe ferramentas de gerenciamento de conexões e todas as ferramentas de planilha da primeira versão. Cada chamada de ferramenta de planilha nesse endpoint exige:

{
  "connection_id": "YOUR_CONNECTION_UUID"
}

Obtenha o UUID com sheetbest_list_connections. Ao usar um endpoint direto, omita connection_id; a URL já fornece esse contexto. Os próximos exemplos mostram argumentos do endpoint da conta.

MCP Inspector com as ferramentas de conexão e planilha expostas pelo endpoint MCP principal do Sheet Best.

Ferramentas da conta

As ferramentas da conta gerenciam seu catálogo de conexões. Elas não consomem requisições mensais de API.

Ferramenta	Função
`sheetbest_list_connections`	Lista suas conexões, incluindo status, métodos, URL de API e URL MCP direta opcional.
`sheetbest_create_connection`	Cria uma conexão a partir de uma URL nativa do Google Sheets e retorna suas URLs de API e MCP direta.

Listar conexões

sheetbest_list_connections aceita:

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

Os dois campos são opcionais. Conexões arquivadas são omitidas por padrão; conexões com MCP desativado são incluídas para que você entenda por que um endpoint está indisponível.

Criar uma conexão

Chame sheetbest_create_connection com:

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

Apenas url é obrigatório. name usa o título ou ID da planilha por padrão e mcp_enabled usa true. A criação verifica seu limite de conexões, o acesso ao Google Sheets e a linha de cabeçalho.

Ferramentas de planilha

Um endpoint direto anuncia apenas as ferramentas permitidas pelas configurações da conexão e pelo plano. O endpoint da conta anuncia o catálogo completo da primeira versão; cada chamada ainda verifica os métodos, o plano, o acesso do Google e a cota da conexão selecionada.

Ferramenta	Requisito	Consome cota se bem-sucedida	Altera dados
`sheetbest_list_rows`	`GET` ativado	Sim	Não
`sheetbest_query_rows`	`GET` ativado	Sim	Não
`sheetbest_get_info`	`GET` ativado e um plano com acesso a consultas avançadas	Sim	Não
`sheetbest_get_limits`	Nenhum	Não	Não
`sheetbest_get_permissions`	Nenhum	Não	Não
`sheetbest_add_rows`	`POST` ativado	Sim	Sim
`sheetbest_update_rows`	`PATCH` ou `PUT` ativado	Sim	Sim
`sheetbest_delete_rows`	`DELETE` ativado	Sim	Sim

sheetbest_aggregate e sheetbest_pivot não estão disponíveis pelo MCP.

Configurações de métodos da conexão com as operações de leitura e gravação permitidas pelo Sheet Best.

Por que uma ferramenta pode estar ausente

Se uma ferramenta não aparecer na lista do cliente:

Verifique Advanced Settings → Methods (Configurações avançadas → Métodos) na conexão.
Confirme se o plano permite a operação. sheetbest_get_info exige acesso a consultas avançadas.
Se estiver usando um endpoint direto, confirme se a conexão permite essa ferramenta.
Reconecte ou atualize o servidor para o cliente solicitar a lista de ferramentas atualizada.

O acesso de edição do Google determina se uma gravação funciona. Os métodos permitidos determinam se a ferramenta de gravação é anunciada.

Abas

A maioria das ferramentas de linhas aceita um argumento tab opcional:

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

Omita tab para usar a primeira aba. Para qualquer outra, use o título exato.

Use sempre a mesma forma

Para leituras e gravações relacionadas na primeira aba, sempre omita tab ou sempre envie seu nome. As duas formas usam caminhos de cache temporários diferentes.

Os mesmos conceitos estão disponíveis na API REST. Consulte trabalhar com abas.

Ler e consultar linhas

Listar linhas

sheetbest_list_rows aceita paginação, valores nativos e filtros de coluna:

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

limit usa 100 por padrão e aceita valores de 1 a 1000.
offset usa 0 por padrão e começa a contar em zero.
columns busca valores exatos ou padrões com o curinga *.
search_ci faz as correspondências de coluna ignorarem maiúsculas e minúsculas.
raw solicita valores nativos das células quando disponíveis.

O resultado inclui rows, totalRows, totalColumns, limit e offset. Consulte os guias REST de filtragem e paginação.

Consultar linhas

sheetbest_query_rows compara valores de coluna. Cada valor de consulta começa com um operador:

Operador	Significado
`__eq`	Igual
`__ne`	Diferente
`__gt`	Maior que
`__gte`	Maior ou igual a
`__lt`	Menor que
`__lte`	Menor ou igual a

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

query é obrigatório. Todas as condições devem ser atendidas. Consulte consultar dados para os conceitos REST correspondentes.

Adicionar linhas

sheetbest_add_rows aceita um objeto ou um array não vazio. As chaves devem corresponder aos cabeçalhos da planilha.

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

Isso altera sua planilha

Revise a conexão, a aba e os valores de destino antes de aprovar a chamada. Uma chamada bem-sucedida conta como uma requisição de API.

Consulte adicionar linhas para a operação REST equivalente.

Atualizar linhas

sheetbest_update_rows exige data e exatamente um seletor:

index: um índice de linha que começa em zero ou uma expressão de índices;
columns: uma ou mais correspondências de coluna.

Por padrão, a ferramenta faz uma atualização parcial como PATCH:

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

Defina put como true para substituir as linhas correspondentes como com PUT. A substituição esvazia as colunas não fornecidas:

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

Confirme se deseja atualizar ou substituir

Use put: false a menos que queira substituir toda a linha correspondente. Confirme o seletor e os dados antes de aprovar qualquer uma das operações.

A conexão deve permitir PATCH para uma atualização parcial ou PUT para uma substituição. Consulte atualizar linhas.

Excluir linhas

sheetbest_delete_rows também exige exatamente um seletor:

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

ou:

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

A exclusão é permanente

A ferramenta exclui todas as linhas correspondentes. Peça ao assistente para listar ou contar as correspondências primeiro e só aprove a exclusão quando o seletor estiver correto.

Consulte excluir linhas para a operação REST equivalente.

Verificar permissões

sheetbest_get_permissions não altera a planilha nem consome cota. Ele separa três tipos de acesso:

{
  "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 informa se a planilha está acessível, é privada, é editável e tem cabeçalhos válidos.
sheetbest informa os métodos configurados e o status do MCP na conexão.
effective informa o que a conexão MCP pode fazer atualmente após combinar essas verificações.

Se o acesso efetivo for menor que o esperado, consulte solução de problemas do MCP.

Consultar a cota

sheetbest_get_limits retorna limit, remaining e plan sem consumir cota. Chamadas bem-sucedidas sobre linhas e sheetbest_get_info contam uma vez. Verificações prévias ou operações que falham não contam como requisições bem-sucedidas.

Próximo passo

Aprenda a proteger e gerenciar seu token MCP.

URLs dos endpoints​

Como funciona o contexto da conexão​

Ferramentas da conta​

Listar conexões​

Criar uma conexão​

Ferramentas de planilha​

Por que uma ferramenta pode estar ausente​

Abas​

Ler e consultar linhas​

Listar linhas​

Consultar linhas​

Adicionar linhas​

Atualizar linhas​

Excluir linhas​

Verificar permissões​

Consultar a cota​

Próximo passo​