Model Context Protocol

Plug GST, e-Invoice & e-Way Bill into your AI assistant — in 60 seconds

The @whitebooks/mcp-server turns the entire WhiteBooks API suite into native tools for Claude, ChatGPT, Cursor, Continue.dev, and Cline. Your agent can verify a GSTIN, generate an IRN, file a return, or update a Part-B — directly from chat. Sandbox-by-default, idempotency keys, confirmation gates on every irreversible action. India's first MCP server for GST compliance.

India's first GST MCP server 28 tools · 5 namespaces Sandbox by default Confirmation gate on irreversible ops OpenTelemetry built-in Apache-2.0

View on GitHub → Get sandbox keys →

60-second install — Claude Desktop

Paste this into ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on Windows:

{
  "mcpServers": {
    "whitebooks": {
      "command": "npx",
      "args": ["-y", "@whitebooks/mcp-server"],
      "env": {
        "WB_CLIENT_ID":     "ck_live_xxx",
        "WB_CLIENT_SECRET": "cs_live_xxx",
        "WB_ENV":           "sandbox"
      }
    }
  }
}

28 tools across 5 namespaces

gst.* (10 tools)

verify_gstin · verify_gstin_bulk
fetch_gstr2b · fetch_gstr1
file_gstr1 · file_gstr3b · file_gstr9
search_hsn · search_sac
gst_calculator

einvoice.* (7 tools)

generate_irn · generate_irn_bulk
cancel_irn · get_irn
fetch_irn_by_doc · sync_irns
health_check

eway.* (8 tools)

generate · generate_bulk
update_partb · update_transporter
extend_validity · cancel
consolidated_generate · get_ewb

ksa.* (3 tools)

einvoice_clearance
einvoice_reporting
get_csid

meta.* (5 tools)

status (live health + latency)
rate_limits (quota for your token)
openapi_spec (introspection)
error_lookup (plain-English fix)
audit_trail

5 bundled prompts

file_monthly_gstr1
reconcile_2b
generate_irn_from_invoice
dispatch_with_eway
vendor_risk_check

Audit-grade safety — built for the agent era

1 — Sandbox by default

Server boots in WB_ENV=sandbox unless the operator explicitly sets production. Prevents "agent accidentally files real returns."

2 — Idempotency on every state-mutating tool

Every file_* / generate* / cancel* / update_* tool auto-derives an idempotency key from a SHA-256 hash of the payload. Agent can retry on network failure without double-generating an IRN or EWB. Caller can override per-call.

3 — Confirmation gate on irreversible ops

First call to *.cancel, *.file_*, or *.generate_credit_note returns requires_confirmation: true + a one-shot confirmation token. Agent must call meta.confirm with the token to actually execute. Blocks Claude/Cursor from filing a return without explicit user OK.

4 — Token isolation

Server holds the WB_CLIENT_SECRET; the agent never sees the access token. Token refresh is automatic and invisible to the agent. PII / GSTIN redaction in logs by default.

5 — OpenTelemetry built in

Every tool emits OTel spans (wb.tool.name, wb.idempotency_key, wb.upstream_latency_ms). HTTP-mode server exposes Prometheus /metrics. Errors flow to meta.error_lookup codes so the agent can render a plain-English fix.

Phased rollout

Phase	Week	Scope
0	1	`meta.status` + `gst.verify_gstin` — validates plumbing end-to-end with Claude Desktop.
1	2–3	Read-only: `gst.fetch_gstr2b/1`, `einvoice.get_irn`, `eway.get_ewb` + all `meta.*`.
2	4–6	Write: `einvoice.generate_irn` (single + bulk), `eway.generate`, `eway.update_partb`, `eway.cancel`. Public launch.
3	7–8	GST returns: `gst.file_gstr1`, `gst.file_gstr3b`. Highest risk; ships behind `--enable-returns` flag.
4	9–10	KSA: `ksa.einvoice_clearance`, `ksa.einvoice_reporting`.
5	11–12	Hosted SaaS HTTP+SSE mode at `mcp.whitebooks.in`.

End of Phase 2 is the launch story: "Generate any e-Invoice or e-Way Bill from your AI assistant — sandbox-safe by default."

FAQ

Is this an official Anthropic / OpenAI integration?

No. MCP is an open protocol authored by Anthropic; anyone can publish a server. This is the WhiteBooks-authored MCP server, available to any agent that speaks the protocol (Claude, ChatGPT, Cursor, Continue.dev, Cline, and future entrants).

Do I need a developer license to use it?

You need a WhiteBooks sandbox API key (free, 5-minute sign-up). The MCP server itself is Apache-2.0 on GitHub.

Can the agent file real returns by mistake?

Not without confirmation. Every irreversible operation (cancel, file_*, generate_credit_note) is gated — the first call returns a confirmation token; the agent must call meta.confirm within 5 minutes to actually execute. Plus the server defaults to sandbox.

Which IDEs / agents are supported?

Anything that speaks the MCP protocol — Claude Desktop, Cursor, Continue.dev, Cline, plus future entrants. Stdio mode for desktop apps, HTTP+SSE mode for cloud / self-hosted agents (Phase 5).

How do I report a bug / request a tool?

Open an issue on GitHub. We review weekly.

Get started

Get a sandbox API key View source on GitHub