MCP API reference

HISAB exposes a local Model Context Protocol (MCP) server. Any MCP-compatible AI client can drive HISAB tools.

What it is

HISAB runs the MCP server in-process inside Excel and exposes the workbook as a set of tools. Your own AI CLI — Anthropic Claude Code (claude) or OpenAI Codex (codex) — connects to it as an MCP client. HISAB never resells AI; the CLI talks to your Anthropic / OpenAI account, and the MCP server just hands it the Excel tool surface. Tools cover reading and writing ranges, writing formulas, running Python, listing and reading skills, building forms and ribbons, and ERP connectors.

HISAB registers itself with the CLIs under the server name hisab, so the tools appear to the AI as mcp__hisab__<tool> (e.g. mcp__hisab__read_range).

Endpoint

The server listens for JSON-RPC 2.0 over HTTP POST at http://localhost:7317/mcp. If port 7317 is busy it walks up through 7318–7320; if the loopback bind needs no URL reservation it falls back to http://127.0.0.1:<port>/mcp. The live URL and port are shown in Settings. An unauthenticated GET /health returns ok for liveness probes.

Every /mcp request needs a bearer token: Authorization: Bearer <token>. The token is 32 bytes of crypto-random base64url, stored owner-only at %APPDATA%\HISAB\mcp-token.txt, and is ALSO published to the HISAB_MCP_BEARER environment variable so a terminal you open yourself can authenticate. The token PERSISTS across Excel restarts — it is regenerated only on first-ever launch, if the file is corrupt, or when you click Reset MCP credentials in Settings.

Tool surface (excerpt)

Only a small set of core tools is advertised on every tools/list to keep per-turn schema cost flat; everything else is reachable through the lazy-discovery trio tool_list / tool_info / tool_call. Output shapes vary per tool — list_sheets returns plain text (one sheet per line), read_values returns a JSON envelope, read_range returns a markdown table.

list_sheets()                              -> text, one line per sheet (name, rows, cols)
read_range(range, sheet?)                  -> markdown table
read_values(range, sheet?)                 -> JSON { summary, counts, rows }
write_cell(cell, value, sheet?)
write_formula(cell, formula, sheet?)       -> formula must start with '='
bulk_write(writes[], sheet?)               -> up to 5000 cells/call
execute_analysis(code)                     -> Python 3.11 sandbox; host.* bridges the workbook
ask_user_choice(question, options?, ...)   -> JSON { "value": "" }
list_skills(filter?) / read_skill(stem)    -> skill catalogue / one skill's markdown
todo_write(steps[], current_step?, done?)  -> live in-chat checklist
set_operating_mode(...) / create_workbook(...)
set_ribbon_xml / read_ribbon_xml / render_ribbon
open_form_designer / open_html_form
erp_list_connections() / erp_query(...) / erp_stage_template(...) / ...
tool_list(category?) / tool_info(name) / tool_call(name, arguments)

JSON-RPC envelope

Methods supported: initialize, tools/list, tools/call, and ping. The advertised protocol version is 2025-06-18. Notifications (requests with no id) get no response, per spec.

POST /mcp HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "abc",
  "method": "tools/call",
  "params": {
    "name": "read_range",
    "arguments": { "sheet": "Bank Statement", "range": "A1:E50" }
  }
}

How the CLIs are wired

HISAB registers the hisab MCP entry into both AI CLIs automatically: Claude Code's ~/.claude.json (under mcpServers.hisab) and Codex's ~/.codex/config.toml (a managed block). Each entry carries the localhost URL and the current bearer token. The HISAB uninstaller removes these entries again when you remove the add-in.

Approvals & operating modes

Tool calls run under the current operating mode. In Action mode, write and destructive tools are queued for your explicit approval before they execute; in Ask-only mode the write / format / structure tools are hidden from tools/list entirely, so the AI cannot even see a write tool. Writes routed through tool_call respect the same gate as calling the tool directly. See Approvals & safety.

Connection status

The MCP pill at the top of the chat tab reflects the live link: amber while the server is bound but no client has talked yet, green once your CLI has made an authenticated request.