MCP Server

The mcp extension exposes the spreadsheet server as a Model Context Protocol server, so AI clients such as Claude Code, Claude Desktop, IDE assistants or your own agents can read and edit spreadsheets through MCP tools. It speaks the MCP Streamable HTTP transport at /mcp.

Enabling it

Install the extension and declare it in the extensions option. /mcp is served on the api extension's HTTP server when present; otherwise the extension creates its own:

npm install @jspreadsheet/mcp

const mcp = require('@jspreadsheet/mcp');

server({
    // ...
    extensions: { api, mcp },
});

GET /mcp/health reports the initialization state and the number of active sessions.

Connecting a client

# Claude Code
claude mcp add --transport http sheets https://sheets.example.com/mcp \
  --header "Authorization: Bearer <token>"

// Claude Desktop (claude_desktop_config.json)
{
  "mcpServers": {
    "sheets": {
      "type": "http",
      "url": "https://sheets.example.com/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

When wiring your own client:

Sessions. The transport is stateful: the first initialize request returns an mcp-session-id header, which must accompany every subsequent request (POST for calls, GET for the notification stream, DELETE to close the session). Idle sessions close after 30 minutes by default; change it with the MCP_SESSION_TIMEOUT environment variable (milliseconds).
Authentication. The Authorization: Bearer <token> header is read on every tool call and flows into the same hooks as every other request, so beforeLoad/beforeChange decide what the client may do with the token it carries. See Login & security.
Browser clients. CORS headers are only sent for origins listed in the MCP_ALLOWED_ORIGINS environment variable (comma-separated). Non-browser MCP clients do not send an Origin header and are unaffected. Request bodies are limited to 10 MB.
Multi-node deployments. Tool calls address documents by guid; with guid-routed instances, route /mcp traffic to the right node the same way as REST traffic.

What the tools do

MCP writes go through the same pipeline as socket and REST edits: the document is loaded through beforeLoad, the change is validated by beforeChange, applied to the live in-memory document, persisted through your adapter and broadcast to connected clients in real time.

Every document tool takes the target guid as its first parameter, plus an optional worksheetId (worksheet id or name; the first worksheet is used when omitted).

Document lifecycle

Tool	Description
`listSpreadsheets`	Documents available to the token's user, served by the `list` server option
`createSpreadsheet`	Create a new document from a configuration object; returns the new guid
`destroySpreadsheet`	Delete a document

Reading

Tool	Description
`getConfig`	Worksheet configuration (columns, dimensions, options); pass `spreadsheet: true` for the whole document
`getData`	Worksheet data, with options for calculated formula values (`processed`), the highlighted selection only (`highlighted`) and filtered rows (`includeFilteredRows`); empty rows are trimmed from the result

Writing

Tool	Description
`setValue`	Set cell values or formulas by coordinates, with an optional `force` flag for read-only cells
`setData` / `setRowData` / `setColumnData`	Bulk data writes
`insertRow` / `deleteRow` / `insertColumn` / `deleteColumn`	Structure changes
`createWorksheet`	Add a worksheet
`setHeader` / `setColumnOptions` / `setProperty`	Column titles, column options and cell properties
`setStyle` / `resetStyle`	Cell styling
`setMedia` / `deleteMedia`	Charts, images and shapes
`paste`	Paste a 2D block of data starting at the given coordinates

The read-only tools (getConfig, getData, listSpreadsheets) carry the MCP readOnlyHint annotation, which clients can use for auto-approval; destroySpreadsheet is annotated with destructiveHint.

MCP or REST?

Use MCP when the caller is an AI client that discovers tools dynamically, the AI agent to put an assistant inside your own application, and the REST API for conventional integrations. All address the same in-memory documents through the same authorization, so they can be mixed. See AI with Jspreadsheet Server for the comparison.