MCP Server Documentation

Everything an AI agent needs to read and write your Google Sheets and Excel spreadsheets over the Model Context Protocol.

Contents

1 Overview 2 Connecting 3 Permissions 4 Filters 5 Tools 5.1 List worksheets 5.2 List rows 5.3 Get cell values 5.4 Create row 5.5 Replace rows 5.6 Update rows 5.7 Delete rows 6 Rate Limits 7 Security 8 Client Setup

hub 1. Overview

The sheet2api MCP server lets an AI agent work with your spreadsheets through tool calls instead of hand written HTTP requests. Each Spreadsheet API you own becomes addressable by name, and the agent reads worksheets, lists rows and writes changes with the tools documented below.

Property Value
Endpoint https://sheet2api.com/mcp/
Transport JSON-RPC 2.0 over HTTP POST with a JSON response body. There is no SSE stream and no GET transport.
Protocol version 2025-03-26
Capabilities Tools only, with listChanged set to false. The server advertises no prompts, resources or sampling.
Authentication A bearer token on every request, initialize included.

Methods

Method Purpose
initialize Negotiates the protocol version and returns the server capabilities.
ping Liveness check. Returns an empty result.
tools/list Returns every tool with its input schema and annotations.
tools/call Runs one tool and returns its result inside a content envelope.

A request that carries no id is a notification. The server accepts it and answers HTTP 202 with an empty body. OPTIONS answers with Allow: POST, OPTIONS, and any other method answers HTTP 405.

Handshake

Open the session with initialize.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": {
      "name": "my-agent",
      "version": "1.0.0"
    }
  }
}

Then read the tool catalogue. Doing this once per session is cheaper than guessing schemas, and it keeps the agent correct when a tool changes.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

vpn_key 2. Connecting

Access is granted with OAuth 2.1 and PKCE is mandatory. There are no shared API keys to copy into a config file. A client discovers the authorization server, registers itself, sends the user through an approval screen and receives a token bound to this MCP server.

Unauthenticated requests

A POST without a valid bearer token answers HTTP 401 and JSON-RPC error code -32001 with the message Authentication required. The response carries the header that tells a compliant client where to start.

WWW-Authenticate: Bearer resource_metadata="https://sheet2api.com/.well-known/oauth-protected-resource/mcp", scope="mcp"

Discovery documents

Document Path
Protected Resource Metadata /.well-known/oauth-protected-resource
Authorization Server Metadata /.well-known/oauth-authorization-server

Both documents are also served with an /mcp suffix, so a client that appends the resource path finds them either way.

OAuth endpoints

Step Endpoint
Dynamic Client Registration /oauth/register/
Authorization /oauth/authorize/
Token /oauth/token/

Dynamic Client Registration means an agent needs no manual client setup. It registers itself and then runs the authorization code flow with PKCE. The only scope is mcp.

What the user sees

The human approving the flow signs in with the Google or Microsoft account that already owns their sheet2api spreadsheets. They approve access for the client, and the issued token is bound to https://sheet2api.com/mcp/. A token issued for another resource is rejected here.

Tokens are managed on the MCP dashboard. A single token can be revoked, or every token belonging to a client can be revoked at once.

Client configuration

A client that speaks Streamable HTTP points straight at https://sheet2api.com/mcp/ and needs nothing else. A client that only speaks stdio needs a bridge, so give it the configuration below.

{
  "mcpServers": {
    "sheet2api": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://sheet2api.com/mcp/"
      ]
    }
  }
}

verified_user 3. Permissions

MCP is off by default. The owner of a Spreadsheet API enables it for that API, one API at a time, so granting an agent access to one spreadsheet says nothing about the others.

Every tool declares the permission it needs, and the server checks that permission against the same read, create, update and delete toggles that gate the REST endpoints. Turning off delete on a Spreadsheet API stops the delete tool as surely as it stops a REST DELETE. A blocked call comes back as a tool error naming the disabled permission.

HTTP Basic auth configured on a Spreadsheet API applies to REST only. MCP access is account level and always goes through OAuth, so Basic credentials are neither sent nor checked on a tool call.

A token reaches only the Spreadsheet APIs owned by the account that approved the flow. Naming an API that account does not own returns the same error as naming an API that does not exist, so an agent cannot probe for other people's spreadsheets. Enable or disable MCP per API from the spreadsheets dashboard.

filter_list 4. Filters

A filters argument selects which rows a tool acts on. Every key is a column name exactly as it appears in the worksheet header row, and every value is a string holding the match expression. Call the discovery tool first if the column names are not already known, because a key that matches no column matches no rows.

These tools accept filters.

Operator Example Meaning
Exact match {"Name": "Alice"} Keeps rows whose Name cell equals Alice. Matching ignores case and surrounding whitespace.
* wildcard {"Email": "*@example.com"} Shell style matching. Use * for any run of characters and ? for a single character.
! negation {"Status": "!Archived"} Keeps rows whose cell does not equal the value.
! with * {"Email": "!*@example.com"} Negation and wildcards combine in one value.
> and >= {"Age": ">18"} Numeric comparison, and => is accepted as a spelling of >=. The column must hold numbers or the call fails.
< and <= {"Price": "<=99.5"} Numeric comparison, and =< is accepted as a spelling of <=.
query_type "query_type": "or" Not an operator but the way several filters combine. It defaults to and, meaning every filter must match.

Several filters combine according to query_type. The default is and, meaning a row must satisfy every filter, and or keeps a row that satisfies any one of them.

build 5. Tools

Below is every tool the server exposes, with the description the protocol sends to clients, the full input schema, a worked request and response, and the errors a call can return. The order is the order tools/list returns.

List worksheets list_worksheets

Read Read only

List the worksheets of a Spreadsheet API together with the column names of each worksheet.

When to use it

Discovery. Call this before any other tool so that the agent learns which worksheets a Spreadsheet API exposes and the exact column names of each one. Every other tool addresses rows by those column names, so guessing them is the most common cause of a failed call.

Annotations

Hint Value Meaning
readOnlyHint true Whether the tool leaves the spreadsheet unchanged.
destructiveHint false Whether the tool can overwrite or remove data that is already there.
idempotentHint false Whether repeating the call with the same arguments has the same effect as calling it once.
openWorldHint true Whether the tool reaches an external system, here the spreadsheet provider.

Parameters

Name Type Required Description
api_name string Required Name of the sheet2api Spreadsheet API to operate on. Use the name shown in the sheet2api dashboard.

Example prompt

“Which tabs and columns are in my Inventory sheet?”

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_worksheets",
    "arguments": {
      "api_name": "inventory"
    }
  }
}

Success response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"Stock\": [\"SKU\", \"Product\", \"Quantity\", \"Price\"], \"Suppliers\": [\"Name\", \"Email\", \"Country\"]}"
      }
    ],
    "isError": false
  }
}

The tool result is JSON encoded into the text content block, so a client parses the text field to get the data.

Errors

Code Message Cause
HTTP 401 / -32001 Authentication required No bearer token, or a token that expired, was revoked or was issued for another resource. The response carries a WWW-Authenticate header pointing at the protected resource metadata so the client can start the OAuth flow again.
-32602 api_name is required The arguments object omitted api_name or gave it a non string value.
-32602 No Spreadsheet API named <name> exists on this account The name does not match any Spreadsheet API owned by the account that granted the token. Names are the slugs shown in the dashboard.
-32000 MCP access is disabled for <name> The owner has not enabled MCP on that Spreadsheet API. It is switched on per API on the configure screen.
-32000 read operations are disabled for <name> The owner turned off the read permission for that Spreadsheet API. The same toggle gates the REST endpoint.
-32000 You are either making requests too fast, or have exceeded the maximum number of requests allowed this month. Upgrade your plan to continue making requests. See documentation: https://sheet2api.com/account/plan The account is over its monthly request allowance, which MCP shares with the REST API. Back off and tell the user to upgrade rather than retrying.
-32603 Internal server error The spreadsheet provider failed or the sheet is malformed. Safe to retry once.

GET /v1/{user_id}/{api_name}/__all__/ is the REST equivalent, documented in the REST API reference.

List rows list_rows

Read Read only

Read rows from a worksheet as JSON objects keyed by column name, optionally filtered and limited.

When to use it

The main read tool. Returns matching rows as JSON objects keyed by column name, in worksheet order. Use filters to narrow the result rather than reading a whole worksheet and filtering in the model, which wastes context and counts the same against the monthly request limit.

Annotations

Hint Value Meaning
readOnlyHint true Whether the tool leaves the spreadsheet unchanged.
destructiveHint false Whether the tool can overwrite or remove data that is already there.
idempotentHint false Whether repeating the call with the same arguments has the same effect as calling it once.
openWorldHint true Whether the tool reaches an external system, here the spreadsheet provider.

Parameters

Name Type Required Description
api_name string Required Name of the sheet2api Spreadsheet API to operate on. Use the name shown in the sheet2api dashboard.
resource string Optional Worksheet (tab) name. Omitted means the first worksheet.
filters object Optional Column name to value pairs used to select rows. Values support wildcards (John*), negation (!John) and relational operators (>18, <100).
limit integer Optional Maximum number of rows to act on.
query_type string (and | or) Optional How to combine multiple filters. Defaults to and.

The filters argument supports wildcards, negation and numeric comparison. See Filters for the full syntax.

Example prompt

“List everything in my Inventory sheet with fewer than 10 units left.”

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_rows",
    "arguments": {
      "api_name": "inventory",
      "resource": "Stock",
      "filters": {
        "Quantity": "<10"
      },
      "limit": 50
    }
  }
}

Success response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"SKU\": \"A-114\", \"Product\": \"Blue Mug\", \"Quantity\": 4, \"Price\": 9.5}]"
      }
    ],
    "isError": false
  }
}

The tool result is JSON encoded into the text content block, so a client parses the text field to get the data.

Errors

Code Message Cause
HTTP 401 / -32001 Authentication required No bearer token, or a token that expired, was revoked or was issued for another resource. The response carries a WWW-Authenticate header pointing at the protected resource metadata so the client can start the OAuth flow again.
-32602 api_name is required The arguments object omitted api_name or gave it a non string value.
-32602 No Spreadsheet API named <name> exists on this account The name does not match any Spreadsheet API owned by the account that granted the token. Names are the slugs shown in the dashboard.
-32000 MCP access is disabled for <name> The owner has not enabled MCP on that Spreadsheet API. It is switched on per API on the configure screen.
-32000 read operations are disabled for <name> The owner turned off the read permission for that Spreadsheet API. The same toggle gates the REST endpoint.
-32602 Worksheet <name> was not found in this spreadsheet The resource argument named a worksheet that does not exist. Call list_worksheets for the current names.
-32000 You are either making requests too fast, or have exceeded the maximum number of requests allowed this month. Upgrade your plan to continue making requests. See documentation: https://sheet2api.com/account/plan The account is over its monthly request allowance, which MCP shares with the REST API. Back off and tell the user to upgrade rather than retrying.
-32603 Internal server error The spreadsheet provider failed or the sheet is malformed. Safe to retry once.

GET /v1/{user_id}/{api_name}/{resource}/ is the REST equivalent, documented in the REST API reference.

Get cell values get_cell_values

Read Read only

Read the values of specific cells, given as a comma separated list of cell references such as A1,B2,C3.

When to use it

Reads named cells by their spreadsheet coordinates rather than by column name. Use it for sheets that are laid out as a form or a dashboard, where a value sits at a known position instead of in a table with a header row.

Annotations

Hint Value Meaning
readOnlyHint true Whether the tool leaves the spreadsheet unchanged.
destructiveHint false Whether the tool can overwrite or remove data that is already there.
idempotentHint false Whether repeating the call with the same arguments has the same effect as calling it once.
openWorldHint true Whether the tool reaches an external system, here the spreadsheet provider.

Parameters

Name Type Required Description
api_name string Required Name of the sheet2api Spreadsheet API to operate on. Use the name shown in the sheet2api dashboard.
resource string Optional Worksheet (tab) name. Omitted means the first worksheet.
cells string Required Comma separated cell references, for example A1,B2,C3.

Example prompt

“What is in cells B2 and B3 of my Budget summary tab?”

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_cell_values",
    "arguments": {
      "api_name": "budget",
      "resource": "Summary",
      "cells": "B2,B3"
    }
  }
}

Success response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"B2\": \"Q3 forecast\", \"B3\": 12400}"
      }
    ],
    "isError": false
  }
}

The tool result is JSON encoded into the text content block, so a client parses the text field to get the data.

Errors

Code Message Cause
HTTP 401 / -32001 Authentication required No bearer token, or a token that expired, was revoked or was issued for another resource. The response carries a WWW-Authenticate header pointing at the protected resource metadata so the client can start the OAuth flow again.
-32602 api_name is required The arguments object omitted api_name or gave it a non string value.
-32602 No Spreadsheet API named <name> exists on this account The name does not match any Spreadsheet API owned by the account that granted the token. Names are the slugs shown in the dashboard.
-32000 MCP access is disabled for <name> The owner has not enabled MCP on that Spreadsheet API. It is switched on per API on the configure screen.
-32000 read operations are disabled for <name> The owner turned off the read permission for that Spreadsheet API. The same toggle gates the REST endpoint.
-32602 Worksheet <name> was not found in this spreadsheet The resource argument named a worksheet that does not exist. Call list_worksheets for the current names.
-32000 You are either making requests too fast, or have exceeded the maximum number of requests allowed this month. Upgrade your plan to continue making requests. See documentation: https://sheet2api.com/account/plan The account is over its monthly request allowance, which MCP shares with the REST API. Back off and tell the user to upgrade rather than retrying.
-32603 Internal server error The spreadsheet provider failed or the sheet is malformed. Safe to retry once.

GET /v1/{user_id}/{api_name}/{resource}/cells/{cells}/ is the REST equivalent, documented in the REST API reference.

Create row create_row

Create

Append a single new row to a worksheet. Keys of the row object must match the worksheet column names.

When to use it

Appends one row to the end of a worksheet. Keys that do not match a column name are ignored, so call list_worksheets first. Creating the same row twice appends it twice, so check with list_rows before retrying a call whose outcome is unknown.

Annotations

Hint Value Meaning
readOnlyHint false Whether the tool leaves the spreadsheet unchanged.
destructiveHint false Whether the tool can overwrite or remove data that is already there.
idempotentHint false Whether repeating the call with the same arguments has the same effect as calling it once.
openWorldHint true Whether the tool reaches an external system, here the spreadsheet provider.

Parameters

Name Type Required Description
api_name string Required Name of the sheet2api Spreadsheet API to operate on. Use the name shown in the sheet2api dashboard.
resource string Optional Worksheet (tab) name. Omitted means the first worksheet.
row object Required Column name to value pairs for the row.

Example prompt

“Add a new supplier called Northwind in Ireland.”

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_row",
    "arguments": {
      "api_name": "inventory",
      "resource": "Suppliers",
      "row": {
        "Name": "Northwind",
        "Email": "[email protected]",
        "Country": "Ireland"
      }
    }
  }
}

Success response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"Name\": \"Northwind\", \"Email\": \"[email protected]\", \"Country\": \"Ireland\"}"
      }
    ],
    "isError": false
  }
}

The tool result is JSON encoded into the text content block, so a client parses the text field to get the data.

Errors

Code Message Cause
HTTP 401 / -32001 Authentication required No bearer token, or a token that expired, was revoked or was issued for another resource. The response carries a WWW-Authenticate header pointing at the protected resource metadata so the client can start the OAuth flow again.
-32602 api_name is required The arguments object omitted api_name or gave it a non string value.
-32602 No Spreadsheet API named <name> exists on this account The name does not match any Spreadsheet API owned by the account that granted the token. Names are the slugs shown in the dashboard.
-32000 MCP access is disabled for <name> The owner has not enabled MCP on that Spreadsheet API. It is switched on per API on the configure screen.
-32000 create operations are disabled for <name> The owner turned off the create permission for that Spreadsheet API. The same toggle gates the REST endpoint.
-32602 Worksheet <name> was not found in this spreadsheet The resource argument named a worksheet that does not exist. Call list_worksheets for the current names.
-32000 You are either making requests too fast, or have exceeded the maximum number of requests allowed this month. Upgrade your plan to continue making requests. See documentation: https://sheet2api.com/account/plan The account is over its monthly request allowance, which MCP shares with the REST API. Back off and tell the user to upgrade rather than retrying.
-32603 Internal server error The spreadsheet provider failed or the sheet is malformed. Safe to retry once.

POST /v1/{user_id}/{api_name}/{resource}/ is the REST equivalent, documented in the REST API reference.

Replace rows update_rows

Update Destructive

Replace every column of the rows matching the filters with the given row. Columns missing from the row are emptied. update_rows_partial leaves omitted columns unchanged.

When to use it

Replaces every column of the matched rows. Any column absent from the row object is emptied, which is why the tool is annotated destructive. Reach for update_rows_partial unless a full row replacement is genuinely what the user asked for.

Annotations

Hint Value Meaning
readOnlyHint false Whether the tool leaves the spreadsheet unchanged.
destructiveHint true Whether the tool can overwrite or remove data that is already there.
idempotentHint false Whether repeating the call with the same arguments has the same effect as calling it once.
openWorldHint true Whether the tool reaches an external system, here the spreadsheet provider.

Parameters

Name Type Required Description
api_name string Required Name of the sheet2api Spreadsheet API to operate on. Use the name shown in the sheet2api dashboard.
resource string Optional Worksheet (tab) name. Omitted means the first worksheet.
filters object Required Column name to value pairs used to select rows. Values support wildcards (John*), negation (!John) and relational operators (>18, <100).
row object Required Column name to value pairs for the row.
limit integer Optional Maximum number of rows to act on.
query_type string (and | or) Optional How to combine multiple filters. Defaults to and.

The filters argument supports wildcards, negation and numeric comparison. See Filters for the full syntax.

Example prompt

“Replace the whole Northwind supplier record with these new details.”

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_rows",
    "arguments": {
      "api_name": "inventory",
      "resource": "Suppliers",
      "filters": {
        "Name": "Northwind"
      },
      "row": {
        "Name": "Northwind",
        "Email": "[email protected]",
        "Country": "Spain"
      },
      "limit": 1
    }
  }
}

Success response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"Name\": \"Northwind\", \"Email\": \"[email protected]\", \"Country\": \"Spain\"}]"
      }
    ],
    "isError": false
  }
}

The tool result is JSON encoded into the text content block, so a client parses the text field to get the data.

Errors

Code Message Cause
HTTP 401 / -32001 Authentication required No bearer token, or a token that expired, was revoked or was issued for another resource. The response carries a WWW-Authenticate header pointing at the protected resource metadata so the client can start the OAuth flow again.
-32602 api_name is required The arguments object omitted api_name or gave it a non string value.
-32602 No Spreadsheet API named <name> exists on this account The name does not match any Spreadsheet API owned by the account that granted the token. Names are the slugs shown in the dashboard.
-32000 MCP access is disabled for <name> The owner has not enabled MCP on that Spreadsheet API. It is switched on per API on the configure screen.
-32000 update operations are disabled for <name> The owner turned off the update permission for that Spreadsheet API. The same toggle gates the REST endpoint.
-32602 Worksheet <name> was not found in this spreadsheet The resource argument named a worksheet that does not exist. Call list_worksheets for the current names.
-32000 You are either making requests too fast, or have exceeded the maximum number of requests allowed this month. Upgrade your plan to continue making requests. See documentation: https://sheet2api.com/account/plan The account is over its monthly request allowance, which MCP shares with the REST API. Back off and tell the user to upgrade rather than retrying.
-32603 Internal server error The spreadsheet provider failed or the sheet is malformed. Safe to retry once.

PUT /v1/{user_id}/{api_name}/{resource}/ is the REST equivalent, documented in the REST API reference.

Update rows update_rows_partial

Update Destructive

Update only the given columns of the rows matching the filters, leaving every other column untouched.

When to use it

Changes only the columns present in the row object and leaves the rest of each matched row alone. This is the right tool for almost every edit an agent is asked to make. Set limit to 1 when the user means a single row.

Annotations

Hint Value Meaning
readOnlyHint false Whether the tool leaves the spreadsheet unchanged.
destructiveHint true Whether the tool can overwrite or remove data that is already there.
idempotentHint false Whether repeating the call with the same arguments has the same effect as calling it once.
openWorldHint true Whether the tool reaches an external system, here the spreadsheet provider.

Parameters

Name Type Required Description
api_name string Required Name of the sheet2api Spreadsheet API to operate on. Use the name shown in the sheet2api dashboard.
resource string Optional Worksheet (tab) name. Omitted means the first worksheet.
filters object Required Column name to value pairs used to select rows. Values support wildcards (John*), negation (!John) and relational operators (>18, <100).
row object Required Column name to value pairs for the row.
limit integer Optional Maximum number of rows to act on.
query_type string (and | or) Optional How to combine multiple filters. Defaults to and.

The filters argument supports wildcards, negation and numeric comparison. See Filters for the full syntax.

Example prompt

“Set Northwind's country to Spain.”

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_rows_partial",
    "arguments": {
      "api_name": "inventory",
      "resource": "Suppliers",
      "filters": {
        "Name": "Northwind"
      },
      "row": {
        "Country": "Spain"
      },
      "limit": 1
    }
  }
}

Success response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"Name\": \"Northwind\", \"Email\": \"[email protected]\", \"Country\": \"Spain\"}]"
      }
    ],
    "isError": false
  }
}

The tool result is JSON encoded into the text content block, so a client parses the text field to get the data.

Errors

Code Message Cause
HTTP 401 / -32001 Authentication required No bearer token, or a token that expired, was revoked or was issued for another resource. The response carries a WWW-Authenticate header pointing at the protected resource metadata so the client can start the OAuth flow again.
-32602 api_name is required The arguments object omitted api_name or gave it a non string value.
-32602 No Spreadsheet API named <name> exists on this account The name does not match any Spreadsheet API owned by the account that granted the token. Names are the slugs shown in the dashboard.
-32000 MCP access is disabled for <name> The owner has not enabled MCP on that Spreadsheet API. It is switched on per API on the configure screen.
-32000 update operations are disabled for <name> The owner turned off the update permission for that Spreadsheet API. The same toggle gates the REST endpoint.
-32602 Worksheet <name> was not found in this spreadsheet The resource argument named a worksheet that does not exist. Call list_worksheets for the current names.
-32000 You are either making requests too fast, or have exceeded the maximum number of requests allowed this month. Upgrade your plan to continue making requests. See documentation: https://sheet2api.com/account/plan The account is over its monthly request allowance, which MCP shares with the REST API. Back off and tell the user to upgrade rather than retrying.
-32603 Internal server error The spreadsheet provider failed or the sheet is malformed. Safe to retry once.

PATCH /v1/{user_id}/{api_name}/{resource}/ is the REST equivalent, documented in the REST API reference.

Delete rows delete_rows

Delete Destructive

Permanently delete the rows matching the filters. Filters are required so that a whole worksheet cannot be emptied by accident.

When to use it

Removes the matched rows from the worksheet. Deletion cannot be undone through the API, and the filters argument is mandatory so that an empty filter set can never clear a worksheet. Confirm the exact rows with list_rows using the same filters before deleting.

Annotations

Hint Value Meaning
readOnlyHint false Whether the tool leaves the spreadsheet unchanged.
destructiveHint true Whether the tool can overwrite or remove data that is already there.
idempotentHint false Whether repeating the call with the same arguments has the same effect as calling it once.
openWorldHint true Whether the tool reaches an external system, here the spreadsheet provider.

Parameters

Name Type Required Description
api_name string Required Name of the sheet2api Spreadsheet API to operate on. Use the name shown in the sheet2api dashboard.
resource string Optional Worksheet (tab) name. Omitted means the first worksheet.
filters object Required Column name to value pairs used to select rows. Values support wildcards (John*), negation (!John) and relational operators (>18, <100).
limit integer Optional Maximum number of rows to act on.
query_type string (and | or) Optional How to combine multiple filters. Defaults to and.

The filters argument supports wildcards, negation and numeric comparison. See Filters for the full syntax.

Example prompt

“Delete the Northwind supplier row.”

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_rows",
    "arguments": {
      "api_name": "inventory",
      "resource": "Suppliers",
      "filters": {
        "Name": "Northwind"
      },
      "limit": 1
    }
  }
}

Success response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"deleted\": true}"
      }
    ],
    "isError": false
  }
}

The tool result is JSON encoded into the text content block, so a client parses the text field to get the data.

Errors

Code Message Cause
HTTP 401 / -32001 Authentication required No bearer token, or a token that expired, was revoked or was issued for another resource. The response carries a WWW-Authenticate header pointing at the protected resource metadata so the client can start the OAuth flow again.
-32602 api_name is required The arguments object omitted api_name or gave it a non string value.
-32602 No Spreadsheet API named <name> exists on this account The name does not match any Spreadsheet API owned by the account that granted the token. Names are the slugs shown in the dashboard.
-32000 MCP access is disabled for <name> The owner has not enabled MCP on that Spreadsheet API. It is switched on per API on the configure screen.
-32000 delete operations are disabled for <name> The owner turned off the delete permission for that Spreadsheet API. The same toggle gates the REST endpoint.
-32602 Worksheet <name> was not found in this spreadsheet The resource argument named a worksheet that does not exist. Call list_worksheets for the current names.
-32000 You are either making requests too fast, or have exceeded the maximum number of requests allowed this month. Upgrade your plan to continue making requests. See documentation: https://sheet2api.com/account/plan The account is over its monthly request allowance, which MCP shares with the REST API. Back off and tell the user to upgrade rather than retrying.
-32603 Internal server error The spreadsheet provider failed or the sheet is malformed. Safe to retry once.

DELETE /v1/{user_id}/{api_name}/{resource}/ is the REST equivalent, documented in the REST API reference.

speed 6. Rate Limits

MCP tool calls draw on the same monthly request allowance as the REST API. There is no separate MCP quota and no separate MCP price. One tool call costs one request, exactly like one REST call.

Going over the allowance returns a tool error, not an HTTP 429. The message is the over limit message listed in every tool's error table above, and it arrives with the normal JSON-RPC error shape.

An agent that sees that error should stop calling tools and tell the user, because retrying cannot succeed until the allowance resets or the plan changes. Reading a whole worksheet and filtering in the model costs the same as a filtered read, so push filters into the call and keep the count down.

Allowances per plan are on the pricing page.

security 7. Security

The server uses OAuth 2.1 rather than shared secrets. Nothing long lived is pasted into a client config, and PKCE is required, so an intercepted authorization code is useless on its own.

Tokens are bound to https://sheet2api.com/mcp/. A token minted for a different resource is refused, which stops a token leaked from another service being replayed here. Scope is limited to mcp.

Revocation is immediate and self service. Drop one token or every token for a client on the MCP dashboard, which also lists recent MCP activity so you can see which client called what.

Only the data an agent asks for leaves the spreadsheet. A tool call returns the worksheet names, columns, rows or cells covered by its arguments, and nothing wider than that. Filters and limit narrow what is sent, so a well scoped call keeps the rest of the sheet private.

Read the privacy policy and the terms of service for how sheet2api handles your data.

devices 8. Client Setup

Claude Desktop and Cursor

Both speak stdio, so they reach a remote server through the mcp-remote bridge. Add the block below to the MCP config of either client and restart it. The bridge opens a browser for the OAuth approval on first use and caches the token afterwards.

{
  "mcpServers": {
    "sheet2api": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://sheet2api.com/mcp/"
      ]
    }
  }
}

ChatGPT and other remote clients

Any client that speaks Streamable HTTP takes the URL on its own. Add https://sheet2api.com/mcp/ as a remote MCP server and the client handles registration, the OAuth flow and the tool listing for you. No bridge and no local process is involved.

For the agent-facing instruction set, see the AI agents page.

link Useful Links

Ready to get started?

Create your first spreadsheet API in less than 60 seconds. No credit card required.

Create Your First API
check_circle No credit card required
check_circle Cancel anytime
Or view our pricing plans