Overview
The SoftLedger MCP Server lets AI assistants — Claude, ChatGPT, Cursor, and other apps that support the Model Context Protocol (MCP) — connect directly to your SoftLedger tenant (company) and answer questions about your books by querying your live data. Ask "which invoices are overdue?", "what bills are unpaid this month?", or "walk me through our chart of accounts" and the AI pulls the answer from SoftLedger itself, not from memory.
The connection is read-only by default. Your company can also let the AI create new records, such as draft journal entries, bills, invoices, customers, and vendors. Every transaction it creates stays in its first status (for example, a draft journal or an unapproved bill) until a person reviews and acts on it in SoftLedger..
Note: The write capability to create new records must be enabled by the SoftLedger team. See Letting the AI create records (MCP Writes) below.
Before you connect: a 5-minute governance check
Because the AI sees whatever the connecting user sees, your existing SoftLedger permissions ARE your AI data policy. We recommend admins do this once, before rolling MCP out to the team:
Review user roles. Confirm each user who will connect an AI assistant has permissions that match what you're comfortable with an AI reading on their behalf.
Check location scopes. Results are automatically limited to the locations a user is assigned to — verify those assignments are current.
Decide what the AI may create. If MCP Writes is turned on for your company, choose which entities the AI can create in System Settings → MCP → MCP Writes. Each entity is off by default, and a user can only create what their role already allows in the app.
Align with your company's AI policy. Your financial data will pass through the AI assistant you connect (Claude, ChatGPT, etc.) under that vendor's data terms. If your company restricts which AI tools may handle financial data, apply that policy here.
Offboarding is automatic. Deactivating a user in SoftLedger ends their MCP access with it, and removing a permission takes effect on the user's next request.
Getting connected
Step 1 — Add SoftLedger in your AI client using the MCP URL for your region:
Region | MCP URL |
United States (your normal login is at app.softledger.com) |
|
EU (your normal login is at eu-app.softledger.com) |
|
Claude (web/desktop): Settings → Connectors → Add custom connector → paste the MCP URL.
ChatGPT: Custom MCP connections are added as plugins and need Developer mode (Plus, Pro, Team, and Enterprise plans; on Team/Enterprise an admin must first allow custom plugins). Open Settings → Plugins and turn on Developer mode. Then open the Plugins menu, click + to create a New Plugin, enter a name, paste the MCP URL under Connection, and choose OAuth under Authentication (leave the client ID and secret blank). Save, sign in, and enable the SoftLedger plugin in your chat.
Claude Code (terminal):
claude mcp add --transport http softledger https://api.softledger.com/mcp(swap in the EU URL if applicable).OpenAI Codex (CLI, IDE extension, or app):
codex mcp add softledger --url https://api.softledger.com/mcp, thencodex mcp login softledger(swap in the EU URL if applicable). In the Codex app, use Plugins → MCP → Add MCP Server → Streamable HTTP and leave the bearer token empty.Other MCP clients (Cursor, etc.): add a remote/HTTP MCP server pointing at the URL.
Step 2 — Sign in and authorize. The client opens a SoftLedger sign-in. Use your normal SoftLedger credentials, pick the tenant (company) you're connecting (if you belong to more than one), and approve the authorization screen. Done — the SoftLedger tools now appear in your AI client.
You'll see the describe and list tools, which read data. A third tool, create, appears only when your user can create at least one entity through MCP Writes.
What the AI can see
The core general ledger details:
general ledger (journal entries and journal lines)
chart of accounts
cost centers, jobs, products
budgets
invoices and invoice lines
customers
bills and bill lines
vendors and vendor credits
cash receipts, payments, and batch payments
locations
contacts (name/email/phone only)
accounting periods and fiscal years
your settings
Not included today (but planned in the future): inventory, crypto, sales/purchase orders, bank feeds, prepaids/fixed assets, and admin functions.
Not included ever: addresses and bank-account details.
Note: the MCP server is not a replacement for the SoftLedger REST API, and there are no dedicated financial-report tools yet — the AI answers by querying and aggregating records, not by running your saved Balance Sheet or Income Statement.
Letting the AI create records (MCP Writes)
The AI can create a record only when all three of these are true:
MCP write access is on for your company. Reach out through the chat bubble or at support@softledger.com to turn it on.
An admin turned on the entity in System Settings → MCP → MCP Writes. Every entity is off by default. The All Entities switch turns every entity on or off at once, and each entity has its own switch.
The user's role can read and create that entity in the app.
Changes apply on the next request. Turning an entity off, or removing the user's create permission, blocks the next attempt right away. Turning an entity on lets the AI create it on the next call, though the client's tool list only shows it after you reconnect the client.
What the AI can create
Entity (switch in MCP Writes) | What the AI creates |
Cost Centers | A cost center |
Jobs | A job for a customer |
Products | A product |
Customers | A customer |
Vendors | A vendor |
Ledger Accounts | A ledger account for a location |
Journals | A journal entry in Draft. Nothing posts to the ledger. |
Bills | A bill in Created status and Unapproved. Every line is an expense line (no prepaid or fixed asset lines). |
Invoices | An invoice in Created status. No AR journal posts. |
Payments | A payment in Created status. Its journal posts when a user approves the payment. |
The AI can't update, delete, post, approve, issue, or void anything. It creates one record per request, and every record follows the same rules as one a user creates in the app: your system settings apply, and the record must use a location in the user's accessible softledger locations.
Payments
Payments follow your company's payment settings. For example, a payment for a bill needs an approved bill unless Allow Draft Bill Payments is on, and a payment for an invoice needs an issued invoice.
Note: A created payment changes its bill or invoice right away. SoftLedger applies the payment as soon as the AI creates it, before anyone approves it. The bill or invoice's amount due drops and its status changes. To undo it, delete the payment in SoftLedger.
If Auto Approve AP Payments or Auto Approve AR Payments is on, SoftLedger would post a new payment on that side immediately. Because the AI only creates records that wait for review, it can't create those payments. Create them in SoftLedger instead.
Tracking what the AI created
Every record the AI creates is logged in the audit log with Type MCP and the signed-in user's email. Filter the Type column by mcp to see only those rows. The signed-in user is the record's preparer, just as if they'd entered it in the app, and SoftLedger sends the same webhooks as when an API client creates the record (for example, Bill CREATE).
What to ask it (examples that work well)
"Which invoices are overdue, and how many days outstanding is each?"
"List unpaid bills due in the next 14 days, grouped by vendor."
"Which vendors are flagged 1099?"
"Show me open accounting periods — is AP closed for July?"
"Find journal entries posted to account 6200 last month and show me the lines."
"Which customers have no email on file?"
"What payment terms does customer X have, and what's their open balance?"
With MCP Writes turned on, you can also ask it to create records:
"Create a draft journal entry to accrue $4,500 of October rent to account 6100, offset to Accrued Liabilities."
"Add a new vendor, Acme Supplies, with Net 30 terms."
"Create a bill from this invoice PDF for vendor X, coded to Office Supplies." (The bill arrives unapproved for review.)
"Set up cost centers for Engineering, Sales, and Operations."
Tips for better answers:
Name the tenant (company) if you have multiple connections ("In SL-Acme, ...").
Determine consolidated or non-consolidated if pulling balances of accounts or reports.
Be specific about dates ("in July 2026" beats "recently").
Ask for the drill-down — invoice, bill, and journal lines are available, so "show the line detail" works.
Large lists page sequentially. If you ask for thousands of rows, the AI fetches page by page — asking it to filter first ("only unpaid, only location X") is faster and more reliable.
Review before you approve. When the AI creates records, open them in SoftLedger and check accounts, amounts, and dimensions before you post, approve, or issue them.
Working with multiple tenants
Each connection is bound to a single softledger tenant — there's no tenant switching inside one connection. If you manage several tenants, add one MCP connection per tenant and sign in to the right tenant on each. Name them with a consistent prefix (e.g., SL-Acme, SL-Globex) so you and the AI can tell them apart; the AI gets a separate set of tools per connection, so a question about SL-Acme can never return SL-Globex data.
Best practices
Verify before you act. AI assistants summarize and interpret — well, but not infallibly. For anything you'll post, pay, or report on, confirm the figures in SoftLedger. Treat the AI as a fast analyst, not the system of record.
Prefer closed periods for reporting questions. Numbers in open periods can still move (FX remeasurement, eliminations, retained earnings, and other close entries post during period close), so point-in-time answers on open periods are provisional by nature.
Start small with MCP Writes. Turn on only the entities your team needs, such as Journals or Bills, and widen it once you're comfortable with the drafts it produces.
Watch for duplicates after a timeout. If a create request times out, the record may still have been created. The AI is told to check with
listbefore retrying, but a quick look in SoftLedger is worthwhile.Reconnect after permission changes. Newly granted permissions (and newly enabled MCP Writes entities) appear in the AI's tool list only after you reconnect the client. (Revoked permissions are enforced immediately.)
One user, one login. Don't share a "service" login for AI access — you'd lose the per-user scoping and audit trail that make this safe.
Coach the AI when needed. The server teaches the AI to explore your data correctly on its own (it discovers what's available, then queries). If it seems confused about what exists, tell it to "describe the available SoftLedger entities first."
Built to be safe
Read-only by default. The AI can read, filter, and explore your financial data. It can create records only for the entities your admin turns on in MCP Writes, and it can never update, delete, post, approve, issue, or void anything.
New transactions wait for review. Journals are created as drafts, and bills, invoices, and payments are created in their first status. Nothing affects your ledger until a person acts on it in SoftLedger. A new dimension or ledger account changes no balance.
Scoped to each user. Everyone connects with their own SoftLedger login. The AI sees exactly what that user can already see in the app, and can create only what that user can create — nothing more. Entities a user can't access aren't just blocked, they're invisible: the AI never learns they exist. Location (branch) restrictions apply automatically.
Fully audited. Every record the AI creates is logged with Type MCP and the user who made it.
Privacy-preserving. The exposed data is a hand-picked financial slice. Street addresses and bank-account details (including vendor bank accounts) are never surfaced, period. Contacts expose only name, email, and phone.
No API keys. Sign-in uses your normal SoftLedger login through our identity provider. There are no keys to create, store, or accidentally leak.
Troubleshooting
Symptom | Likely cause / fix |
An entity the user works with is "missing" | The signed-in user lacks read permission for it in SoftLedger, or the permission was granted after connecting — grant it, then disconnect/reconnect the client. |
Results seem incomplete | Location scope: users only see records in locations they're assigned to. Check the user's location assignments. |
Query errors mentioning invalid fields | Harmless — the AI is told the valid fields and will self-correct and retry. |
Two companies' data seem mixed up | Check your connection names; add one clearly named connection per tenant ( |
The AI says it can't create records at all, or there's no | MCP write access isn't on for your company, or no entity is turned on for this user. Contact SoftLedger support to enable MCP Writes, have an admin turn on entities, then reconnect the client. |
The AI can't create a specific entity | Ask the AI why; it will check and report one of these reasons. tenant_off: the entity is off in MCP Writes, so an admin turns it on. no_permission: the user's role can't create it, so an admin grants the permission. auto_approve: Auto Approve AP and AR Payments are on, so create the payment in SoftLedger. |
A bill's or invoice's balance changed after the AI made a payment | Expected: a created payment applies to its bill or invoice immediately, before approval. Delete the payment in SoftLedger to undo it. |
A record appears twice | A create request likely timed out and was retried. Delete the extra draft in SoftLedger. |
FAQ
Can the AI change anything in my books? Only if your company turns on MCP Writes, and then only by creating new records for the entities your admin allows. New journals, bills, invoices, and payments wait for a person to post, approve, or issue them. One exception: a created payment is applied to its bill or invoice right away. The AI can never update, delete, post, approve, issue, or void a record.
Who decides what the AI can create? Your admins. SoftLedger turns on MCP write access for the company, an admin picks the entities in System Settings → MCP → MCP Writes, and each user's role still limits what they can create.
Can I see what the AI created? Yes. Filter the audit log Type column by mcp. Each row shows the user who made it.
Does SoftLedger send my data to the AI vendors? SoftLedger only answers the queries your own authorized AI client makes on your user's behalf. How the AI vendor handles data in your chats is governed by your agreement with that vendor — check their data-handling terms, especially for free-tier plans.
Is this the same as the SoftLedger API? No — it's a narrower, curated surface designed for AI assistants: read access plus draft-only creation of a few record types. For integrations and automation, use the REST API.
Who can connect? Any user of a company using their own SoftLedger login, seeing only what their role and locations allow.

