What a connected agent can do

An AI agent connected to your account can look at your services, build new ones from a spreadsheet, test them, publish them and calculate with them. This page lists every action in the order of a typical job.

The idea

You connect an AI to your account once, at https://spreadapi.io/mcp. From then on the agent works with a fixed set of eleven actions. Each action needs one right; the connection's level decides which rights it has. See Rights and limits of a connection.

To connect an AI, see Connect Claude, Connect ChatGPT or The AI agents page.

The actions in the order of a typical job

The shortest path from a spreadsheet to a result is: create_service → set_parameters → test_service → publish_service → run_service.

Draft and published

A service an agent creates is a draft. A draft can be read, changed and tested, and nobody else can call it. Only publish_service makes it callable. After changing cells, parameters or settings of a published service, the agent must publish again: callers keep getting the old version until then.

SpreadAPI tells every agent to publish only when the user asked for it.

What the agent gets back

Every answer has the same form:

• ok: true or false, and the name of the action;
• the action's own fields, for example service_id, status, outputs;
• links: the addresses of the service (editor_url, and for a published service rest_url, mcp_url, discovery_url);
• options: the sensible next calls, ready to send;
• tell_your_user: a sentence the agent should pass on to you;
• warnings: things that worked but deserve a look;
• on failure error with a code, a message and often problems that name each field. See Agent errors.

What an agent cannot do

• Unpublish or delete a service. You do that in the app. See Publish and republish and Manage services.
• Change single cells of an existing workbook, or replace the workbook of an existing service. To change a model, the agent creates a new service from the changed workbook, or you edit the workbook in the editor.
• Create or revoke service tokens. update_service can switch token protection on; you create the tokens under API → Access (API → Zugriff).
• Change connections, rights, the plan or anything else about the account.
• Reach services that are not on its list, or services of another account.

Good to know

• Calls through a connection need no service token, also for protected services: the connection is the access.
• test_service is free of the call count; run_service counts.
• A workbook that was last saved in the editor cannot be read by describe_workbook, read_cells, set_parameters, test_service and publish_service; they answer workbook_not_readable. Such a service can still be described, renamed, protected and run. Continue with cells and parameters in the editor.
• What every agent did is listed under Recent activity (Letzte Aktivität) on the AI agents (KI-Agenten) page.

For developers and agents

Address: https://spreadapi.io/mcp. MCP over streamable HTTP (JSON-RPC 2.0 by POST); methods initialize, tools/list, tools/call, ping. Each action is one tool with the same name, an input schema, an output schema and the hints readOnlyHint and destructiveHint.

Arguments

The workbook in create_service

• sheets: a list of sheets, each with name, cells (rows from top to bottom, each row a list of cells) and optionally start (top-left cell, default A1).
• A cell is a number, a text, true, false or null for an empty cell. A text that starts with = is a formula in Excel syntax with English function names and , between arguments. A text such as "4%" is stored as 0.04 and marked as a percentage.
• At most 20 sheets and 50,000 cells per call.
• xlsx_base64: an .xlsx file, base64 encoded, for files up to 100 KB.
• For workbooks up to 100 formulas the answer carries suggested_parameters; for larger ones a note says to choose the cells with read_cells and set_parameters.

{ "name": "Loan calculator",
  "sheets": [ { "name": "Loan", "cells": [
    ["Loan Amount", 200000],
    ["Annual Rate", "4%"],
    ["Years", 20],
    [null, null],
    ["Monthly Payment", "=-PMT(B2/12,B3*12,B1)"],
    ["Total Paid", "=B5*B3*12"]
  ] } ] }

Parameters in set_parameters

An input is one cell without a formula; an output is a cell or a range. Per parameter only address is required (with its sheet, for example Loan!B2 or Rates!A2:C9); the rest is read from the workbook.

• For inputs and outputs: address, name, title, description.
• For inputs also: type (number, string, boolean), required, percentage, min, max, allowed_values, default.
• The call replaces all inputs and outputs at once. If one does not fit the workbook, nothing is saved and problems says what to change.
• An input whose cell is empty in the workbook is optional by default.

Results of test_service and run_service

{ "ok": true, "action": "run_service", "service_id": "<service_id>",
  "inputs":  { "loan_amount": 150000, "annual_rate": 0.045, "years": 15 },
  "outputs": { "monthly_payment": 1147.49, "total_paid": 206548.19 } }

• inputs and outputs are objects keyed by parameter name; inputs includes defaults.
• A range output is a list of rows. A cell error is { "error": "#N/A" }.
• display holds, for outputs with a number format, the value as the spreadsheet shows it. Quote display to the user and compute with outputs.

list_services and describe_service

• list_services returns services (each with service_id, name, description, status draft or published, links) and total. Up to 100 services are listed.
• describe_service returns name, description, status, requires_token, ai_description, usage_guidance, presentation_guidance, usage_examples, parameters (inputs with type, required, min, max, default, allowed_values, percentage, hint; outputs) and links.

FAQ

What can an AI agent do in my SpreadAPI account?

Within the rights of its connection it can list and describe your services, create a service from a spreadsheet, set inputs and outputs, test, describe, publish and calculate. It cannot unpublish, delete or change anything about the account.

Which actions does the account MCP server offer?

Eleven: what_can_you_do, list_services, describe_service, describe_workbook, read_cells, create_service, set_parameters, update_service, test_service, publish_service and run_service.

Can an agent delete or unpublish my services?

No. There is no action for either. You unpublish or delete a service yourself in the app.

Can an agent upload my Excel file?

It can send an .xlsx file of up to 100 KB as xlsx_base64, or send the cells of the workbook as sheets with up to 20 sheets and 50,000 cells. For a larger file, import it yourself in the app and let the agent continue from there. See Import Excel.

Can an agent edit a workbook I already imported?

It can read it and set its inputs and outputs, but it cannot change single cells or swap the workbook. Change the workbook in the editor, or let the agent create a new service from the changed cells.

What is the difference between test_service and run_service?

test_service calculates on the draft, is not counted and needs the build right. run_service calculates on the published service, is counted like any other call and needs the run right.

Does an agent need a token for a protected service?

No. A connection acts for the account owner, so run_service works without a service token. Other callers still need one.

As an agent, how do I find the id of a service?

Call list_services; each entry has a service_id. create_service also returns the service_id of the new draft.

As an agent, how do I learn which inputs a service expects?

Call describe_service with the service_id. It returns every input with type, whether it is required, limits, allowed values and a hint for percentages.

As an agent, where do I find the full manual?

Call what_can_you_do with guide set to workbook, parameters, publishing, errors or limits. Without guide you get the action list, the typical order and your account.