How to build an MCP server for SAP Business One
Short answer
An MCP server for Business One is a small program that logs in to the Service Layer, exposes a short list of read-only tools such as item lookup and order status, and returns compact JSON to any MCP client. Start with five or six tools, scope the B1 user tightly, and add audit logging before inviting users.
The Model Context Protocol gives AI clients a standard way to call tools. For Business One, that means one server can serve Claude, ChatGPT-compatible clients and in-house agents without rewriting the integration each time. The work is in choosing tools that fit how B1 users really ask questions.
B1 has its quirks. Document types are split across header and row tables, authorisations are per user, many customers rely on UDFs, and the Service Layer has its own session behaviour and paging. A server that ignores these will return plausible but wrong data.
This page describes a tool list, a build sequence and the points where B1 specifically bites, such as licences and document status codes.
What teams use it for
Item and stock lookup
A tool returning item master data plus on-hand, committed and ordered by warehouse, built from Items and warehouse-level data.
Sales order status
A tool taking a document number and returning header status, line status, linked deliveries and invoices.
Open purchase orders by vendor or item
Used by buyers and planners to see what is arriving and when, with promised dates.
Bill of materials explosion
A tool reading the product tree (OITT/ITT1) to answer what components an assembly needs and where each is short.
Business partner profile
Contact, payment terms, credit limit and open balance for a customer or vendor, with sensitive fields filtered by role.
Draft creation, later
After read-only tools prove stable, add a tool that creates a draft purchase order or sales quotation for review.
SAP Business One integration surface
- Service Layer login: a POST to the Login endpoint with CompanyDB, UserName and Password returns a session; the server must reuse it and re-login when it expires.
- Entity endpoints: Items, Orders, PurchaseOrders, DeliveryNotes, Invoices, BusinessPartners, ProductTrees, ProductionOrders and Drafts, queried with $filter, $select, $top and paging.
- SQLQueries: stored queries callable with parameters, handy for aggregations that are awkward through entity endpoints. Availability depends on version.
- Document status fields: DocumentStatus, Cancelled and line status flags must be interpreted correctly, otherwise closed or cancelled documents appear as open.
- $batch support: lets the server bundle several requests, useful for tools that assemble header, rows and linked documents.
- UDF handling: UDF fields appear with a U_ prefix, so tool schemas should list the ones that matter to your business.
How it works
- 1
Define the tool contract first
Write names, descriptions, input schemas and output shapes for each tool before coding. Clear descriptions help the model pick the right tool and avoid overlap.
- 2
Pick the transport
stdio is simplest for a single user running the server locally. For a team, run an HTTP transport behind your reverse proxy with authentication and TLS.
- 3
Implement Service Layer access
Create a client class that handles login, cookie reuse, retries on session expiry and paging. Keep timeouts short and surface errors with plain messages.
- 4
Map users to permissions
Either use one read-only B1 user for the server, or map each MCP client identity to a B1 user so authorisations apply per person. The second costs more licences but is more accurate.
- 5
Shape responses
Return only the fields needed, convert codes to labels, and cap rows with a clear truncation note. Include document keys so users can verify in B1.
- 6
Log and test
Write each call with caller, tool, parameters and row count to an audit log. Test against a copy company, including cancelled documents and multi-warehouse items.
Example flows
Item availability tool call
Trigger: A client calls get_item_availability with an item code.
- The server validates the code format.
- It reads the item and warehouse-level quantities via the Service Layer.
- It adds open purchase order quantities and dates.
- It returns a compact JSON object with a truncation flag if needed.
Result: Any MCP client can answer stock questions consistently.
Draft PO tool with confirmation
Trigger: An agent proposes a purchase for a short item.
- The server checks that the vendor and item exist and are active.
- It posts to Drafts rather than PurchaseOrders.
- It records the draft key and the requesting identity in the audit log.
- It returns the draft key for human review.
Result: A buyer finds a ready draft, and approvals stay in B1.
Keeping data on-prem
An MCP server is naturally on-prem friendly because it is just a process near the Service Layer. Run it on the same network segment or the B1 server itself if resources allow, and put a reverse proxy with TLS and authentication in front for remote clients. Pair it with a locally hosted open-weight model when data cannot leave, or let desktop clients on the corporate network use approved hosted models while the server stays internal. Because the protocol is open, you are not locked to one model vendor, which also makes later model changes cheap.
Security checklist
- Use least-privilege B1 users and keep credentials in a secrets store.
- Authenticate all HTTP clients; never leave the endpoint open on the LAN.
- Validate and parameterise every input; never build OData filters by string concatenation from model text.
- Rate-limit and cap result sizes to protect the B1 server.
- Keep an audit log and review it regularly.
Ways to get it done
Reuse an open-source SAP MCP server
Effort: Low to evaluate, uncertain to adapt.
Only if it clearly supports the Business One Service Layer; many target S/4HANA or ECC.
Write your own with an MCP SDK
Effort: One to four weeks for a first release.
Typical choice: full control over tools, caching and permissions.
Have a partner build and maintain it, such as Netray
Effort: Scoped project with a handover.
Useful if you lack B1 and AI skills in one team and want on-prem model hosting too.
Pitfalls
- !Exposing too many overlapping tools, which makes models pick wrongly.
- !Treating cancelled or closed documents as open.
- !Building filters from raw model text, which invites injection and malformed queries.
- !Opening one session per call and exhausting Service Layer capacity or licences.
- !Forgetting to retest after a B1 upgrade or patch.
Frequently asked questions
What tools should a first B1 MCP server expose?
Start read-only: item lookup with stock, sales order status, open purchase orders, BOM explosion, and business partner profile. These cover most questions and are easy to verify against B1. Add drafts later, once the team trusts the reads and has an audit trail.
Should the server use the Service Layer or SQL directly?
The Service Layer is the safer default because it respects business object logic and authorisations. Direct SQL on a read-only reporting copy can be faster for aggregates, but it bypasses B1 permissions, so use it deliberately and only for data you are comfortable exposing.
stdio or HTTP transport?
Use stdio for a single user testing locally, since there is no network exposure. Use an authenticated HTTP transport for shared team use, placed behind TLS and a proxy. Check what your target clients support, as support varies across tools and versions.
Which clients can use it?
Any client that speaks MCP can call the same server, including Claude clients, other assistants that have added MCP support, and in-house agents. Because behaviour differs between clients, test your tools with each one you plan to support.
Does each tool call consume a B1 licence?
The Service Layer session belongs to a B1 user, and that user's licence type applies. Reusing a single session keeps usage low, but terms around integration access vary by contract. Confirm with your SAP partner before rolling out per-person identities.
Want MCP server working on your SAP Business One?
A free 30 minute assessment: we map the integration path for your version and setup, and where it should run.
Get a free assessment