Integration · MCP v 1.0.0 JSON-RPC 2.0 Streamable HTTP Last updated 2026-05-07

Plug Claude
into your books.
Audit-logged.

SupaLedger speaks the Model Context Protocol — the same language Claude uses to read filesystems, query databases, and call APIs. Read trial balances, age receivables, hand work to Sam, propose journal entries — every call org-scoped, audit-attributed, and HIPAA-aware.

Server endpointOnline · 99.97%
POST · production
https://jztjsserurylfjqfbntx.supabase.co/functions/v1/mcp-server/mcp
Tools
24
Auth paths
3
Per-org RPM
200

What an agent can do in here.

Three verbs across the entire surface. Read business state. Delegate messy work to one of seven AI personas. Export reports as PDFs with one-hour signed URLs.

01
Read

Books, open.

Trial balance, P&L, balance sheet, AR / AP aging — summary or detail. Search journals, contacts, invoices, bills. Org context with active modules.

  • tbTrial balance · summary or per-account
  • plProfit & Loss with sub_type classification
  • bsBalance sheet by current/non-current/equity
  • arReceivables aging · 5 buckets
  • apPayables aging · symmetric
  • ixSearch transactions, contacts, daily briefing
02
Delegate

Hand it to Sam.

Drop a natural-language task on the supervisor agent. Sam routes to Avery, Casey, Riley, Sage, Quinn, or Morgan — and you get the result with child tasks attached.

  • samSupervisor agent · routes to specialists
  • averyAccounting · journals + reconcile
  • caseyCollections · gentle to firm
  • rileyFront desk · inbound triage
  • sageScheduling · capacity-aware
  • morganReporting · BI & commentary
03
Export · Propose

PDFs & proposals.

Render any of five reports to PDF with a 60-minute signed URL. Or stage a write — record_expense, create_invoice, post_journal_entry — for the user to confirm in-app.

  • pdfP&L · BS · TB · AR · AP renders
  • url1-hour signed download URL
  • emailOr delivered straight to inbox
  • stagePropose · ~50 action types
  • confirmUser approves in-app or via MCP
  • auditexecute_proposal stamps confirmed_by
Can't do yet Direct financial writes. Every state-changing action is mediated by Sam and the agent_proposals confirm gate. External agents propose; SupaLedger personas execute.

Three ways
in. One way out.

Every authenticated request resolves a client_id for audit attribution. OAuth tokens are org-scoped at consent time — the chosen org id lands in the JWT as mcp_org_id so every tool call is automatically org-bounded.

Recommended · End-users

OAuth 2.1
+PKCE

For Claude.ai connectors
Authorization: Bearer <user JWT>
  • Org-scoped at consent — user picks the org
  • custom_access_token_hook injects mcp_org_id
  • Tool calls enforce args.org_id == jwt.mcp_org_id
  • Required for write tools & query_business_ai

Service role
bearer

Server-to-server backends
Authorization: Bearer <SERVICE_ROLE_KEY>
x-mcp-client-id: my-integration
  • Use only from a trusted backend
  • x-mcp-client-id tags audit log entries
  • Allowlist via mcp_external_clients
  • Read tools today; write path on roadmap
Rejected

Anonymous
access

No header at all
Response: SL-AUTH-600
Body: Authentication required.
  • Every tool returns SL-AUTH-600
  • Pre-auth audit row written with mcp:anonymous
  • Counts against rate-limit subsystem
  • The string mcp_connector is a reserved tombstone

The ledger
of capabilities.

24 tools as of 2026-05-07. Every tool requires org_id. Every response carries a _meta envelope with server_time, api_version, and freshness notes — use it to invalidate cached answers.

Read · safe Delegation Write · proposal-gated Async / polling Webhook Export · PDF
#
Tool
What it does
Kind
Auth
Rate
01
platform_get_org_context
Org summary OR list every org the caller can reach. HIPAA orgs silently filtered.
Read
OAuth · Service
200 / min
02
accounting_get_trial_balance
Per-account debits/credits/balance. Summary or detail. Point-in-time.
Read
OAuth · Service
200 / min
03
accounting_get_profit_and_loss
P&L over a period. Income/expense by canonical account_type — not sign heuristic.
Read
OAuth · Service
200 / min
04
accounting_get_balance_sheet
Detail rows with sub_type so you can derive current vs non-current vs fixed.
Read
OAuth · Service
200 / min
05
accounting_get_ar_aging
Receivables in 5 buckets · current, 1–30, 31–60, 61–90, 90+.
Read
OAuth · Service
200 / min
06
accounting_get_ap_aging
Payables aging — symmetric to AR. Empty-state returns a message + zeros.
Read
OAuth · Service
200 / min
07
accounting_search_transactions
JE-header level search · entry_number, date, description, contact_names, amount.
Read
OAuth · Service
200 / min
08
crm_search_contacts
Summary mode returns no PII. Detail adds email/phone/address — explicit ask only.
Read
OAuth · Service
200 / min
09
get_daily_briefing
Composite cash + AR + AP + headlines bundle. Cheap — no LLM call.
Read
OAuth · Service
200 / min
10
delegate_to_sam
Hand a task to the supervisor agent. Hardened — jailbreak redactor + boundary markers.
Delegate
OAuth · Service
10 / min · 100 / hr
11
get_task_status
Poll for the result. External callers can only read tasks they themselves created.
Delegate
OAuth · Service
200 / min
12
query_business_ai
Natural-language Q&A · single tool covers 14 reports + 14 entity searches + proposals.
Write·may
OAuth only
200 / min
13
propose_action
Stage a draft proposal · ~50 action types · user confirms in-app or via MCP.
Write
OAuth only
200 / min
14
get_proposal_status
Read state · pending / approved / executed / rejected / expired / failed / cancelled.
Read
OAuth only
200 / min
15
confirm_proposal
Calls execute_proposal(). Pre-flight checks ownership · pending · expiration. Destructive.
Write
OAuth only
200 / min
16
cancel_proposal
Idempotent on terminal states · returns cancelled_now: false.
Write
OAuth only
200 / min
17
extract_document
Pre-upload to org-documents bucket, then extract structured data · 13 doc classes.
Async
OAuth only
200 / min
18
get_extraction_status
Poll · 5 terminal states · complete · review_needed · manual · failed · proposal_id link.
Async
OAuth only
200 / min
19
register_webhook
Subscribe to events · proposals + inbox · 64-char HMAC secret shown ONCE.
Webhook
OAuth only
200 / min
20
list_webhooks
secret_prefix + is_enabled + last_delivery_at + consecutive_failures.
Webhook
OAuth only
200 / min
21
delete_webhook
Idempotent · returns deleted: false when id doesn't exist.
Webhook
OAuth only
200 / min
22
get_webhook_deliveries
Recent log · pending / succeeded / retrying / failed / dead_letter / dropped_4xx.
Webhook
OAuth only
200 / min
23
accounting_list_report_types
Static catalog · pl · balance_sheet · trial_balance · ar_aging · ap_aging.
Read
OAuth · Service
200 / min
24
accounting_export_report
Render PDF · 1-hour signed URL · or email · 50 MB cap.
Export
OAuth · Service
200 / min
§ 02 · Quick start

Three steps. Then your agent reads.

Pick a transport, set a header, call a tool. The MCP TypeScript & Python SDKs handle the JSON-RPC framing — but raw curl works too.

01
Choose your auth path
OAuth user JWT · service-role key · (anonymous rejected)
02
Discover orgs you can reach
platform_get_org_context · returns array · HIPAA orgs hidden
03
Call any of 24 tools
org_id from step 2 · response carries _meta envelope
Browse the full tool catalog
# 1 · List available tools — service-role bearer
curl -X POST "https://jztjsserurylfjqfbntx.supabase.co/functions/v1/mcp-server/mcp" \
  -H "Authorization: Bearer $SUPALEDGER_SERVICE_ROLE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-mcp-client-id: my-integration-name" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# 2 · Pull a P&L for a known org
curl -X POST "…/mcp-server/mcp" \
  -H "Authorization: Bearer $SUPALEDGER_SERVICE_ROLE_KEY" \
  -H "x-mcp-client-id: my-integration-name" \
  -d '{
    "jsonrpc": "2.0", "id": 2,
    "method": "tools/call",
    "params": {
      "name": "accounting_get_profit_and_loss",
      "arguments": {
        "org_id":     "<uuid>",
        "start_date": "2026-01-01",
        "end_date":   "2026-03-31",
        "format":     "summary"
      }
    }
  }'
§ 04 · Freshness envelope

Every response carries a _meta envelope.

Server time, API version, and freshness notes — auto-injected on every tool response. Use _meta.server_time to invalidate cached answers, and read _meta.notes for staleness caveats specific to that tool.

Tool response · accounting_get_profit_and_loss200 OK
{
  …tool result…
  "period": { "start""2026-01-01", "end""2026-03-31" },
  "net_income"42000,
"_meta": {
  "server_time""2026-05-07T17:30:00.000Z",
  "api_version""1.0.0",
  "docs""https://www.supaledgers.com/mcp",
  "notes": [
    "Numeric values are point-in-time as of the report date.",
    "Bank-feed imports may lag 24-48h."
  ]
 }
}
§ 06 · Audit redaction

Free-text caller input is hash-redacted.

Every tool call writes one row to platform.mcp_audit_log. Free-text fields (query, instruction, title, subject) are never stored in plaintext — they're replaced with a redaction stub. Structural args are preserved verbatim for forensics.

mcp_audit_log · row 819,204delegate_to_sam
org_id
7c3c…f2a1
client_id
my-integration-name
tool
delegate_to_sam
title
{ _redacted: true, length: 47, sha256_prefix: 9b1d3f7a8e6c2042 }
instruction
{ _redacted: true, length: 312, sha256_prefix: a04e1c…b87f }
format
summary
delivery.email
ops@field-llc.example
Duplicate detection still works via sha256_prefix · forensics keep enums & ids verbatim.
§ 07 · Error codes

When things go wrong.

All errors return a structured envelope with a stable code string. Treat the code as the contract — error message text may change between minor versions.

Code
Meaning
SL-AUTH-600
Authentication required. Add a Bearer token.
SL-AUTH-001
OAuth user not found. Re-authenticate.
SL-AUTH-002
User not member of target org.
SL-AUTH-003
Org mismatch · JWT mcp_org_id ≠ args.org_id.
SL-AUTH-004
Service-role caller targeting an org outside the allowlist.
SL-MCP-400
Bad input · missing required param, invalid enum.
SL-MCP-429
Rate limit exceeded · per-org or per-user.
SL-MCP-503
Rate-limit subsystem unavailable · fail-closed.
SL-MCP-RATE-LIMIT
Structured delegate_to_sam envelope · retry_after_seconds.
SL-MCP-AUTH-001
External client not provisioned in mcp_external_clients.
SL-AGENT-DELEGATE-001
delegate_to_supervisor RPC failed.
SL-AGENT-TASK-404
Task not found · or hidden by external-client guard.
SL-AGENT-PROPOSAL-409
Proposal not in pending state · cannot confirm.
SL-AGENT-PROPOSAL-410
Proposal expired · re-stage with propose_action.
SL-PLATFORM-004
Database query failed · retry · contact support if persistent.
SL-PLATFORM-005
PDF render failed.
§ 08 · Rate limits

Three counters. Fail-closed.

Per-org and per-user limits are enforced via mcp_audit_log count queries. Failures fail-closed with SL-MCP-503.

Tool calls · per org
200/min
Tool calls · per user
60/min
delegate_to_sam · per org
10/min
delegate_to_sam · hourly
100/hr
Per-client_id overrides shipped · mig 756 · 2026-05-07

Privacy. Audit.
Data handling.

SupaLedger does not transit your prompts to any LLM. Sam internally uses Claude when processing a delegate_to_sam task; the task UI shows exactly what was sent. Every external request is auditable by org admins.

Residency

AWS us-west-2

All data lives in Supabase Postgres, US West 2. Logical replication for backups; no cross-region replication.

Default mode

Summary first

Every tool defaults to format: "summary". Detail mode (PII like emails, phones, line items) only on explicit caller request.

HIPAA orgs

Excluded entirely

Flagged orgs are silently filtered out of org-context listings; direct calls against their org_id return SL-AUTH-001.

Audit

Free-text redacted

Caller-supplied free-text never stored in plaintext. SHA-256 prefix preserved for duplicate detection; structural args verbatim.

Boundaries

Prompt fences

Every delegate_to_sam string is run through a jailbreak-phrase redactor and wrapped in <external_instruction> markers.

Visibility

Every call.

Org admins can query platform.mcp_audit_log for every external request — actor type, client id, tool, timestamps.

Five phases.
Mostly shipped.

Status as of 2026-05-07. Phases 1 → 4 done. Phase 5 evolution capabilities partially landed; OAuth Dashboard toggle & Anthropic Connectors Directory submission still in flight.

Phase 01 · Done

Enable external agents

  • OAuth 2.1 server · code complete
  • Dashboard toggle · in flight
  • CORS allowlist as config table
  • client_id differentiation
Phase 02 · Done

The killer primitive

  • query_business_ai · OAuth path
  • 14 reports · 14 entity searches
  • 15 detail types · proposals
  • Service-role bypass · roadmap
Phase 03 · Done

Action capabilities

  • propose_action · ~50 types
  • get_proposal_status
  • confirm_proposal · destructive
  • cancel_proposal · idempotent
Phase 04 · Done

Push, not pull

  • 4 webhook tools shipped
  • HMAC-signed delivery
  • Retry · 1m · 5m · 15m · 1h · 6h · 24h
  • Freshness _meta envelope
Phase 05 · Partial

Capability evolution

  • extract_document async tools
  • Per-client_id rate limit overrides
  • Inline base64 mode · roadmap
  • Webhook KMS encryption-at-rest
24 tools shipped OAuth 2.1 PKCE HIPAA exclusion Dashboard OAuth toggle Connectors Directory submission

Read the books.
Run the errands.

Connect Claude to your SupaLedger org in a coffee break. Free until May 30, 2026 — service-role key on signup, OAuth on Dashboard toggle.

Support · privacy@fieldelevate.com Field Elevate Management LLC · Durham, NC Reviewer account · reviewer@supaledger.app