How to build an MCP server for TOTVS Protheus
Short answer
An MCP server for Protheus is a small service that exposes a few read-only tools, such as order lookup and stock position, backed by REST services or SQL views with branch scoping. MCP clients like Claude and ChatGPT then call them without custom glue per client.
Protheus has no single canonical API surface. Depending on release and installed modules you may have standard REST endpoints, custom WsRestFul or TLPP services written by your consultants, and a database that your reporting team already queries. An MCP server gives that mixed surface one consistent, documented face for AI clients.
The design question is not how many tools you can expose but which few are safe and useful. Start with lookups that map to what planners, buyers and sales desks ask every day, make them read-only, and make them scope by company and branch.
Because the server will run next to the application server in most on-prem sites, its deployment, authentication and logging matter as much as its tool list.
What teams use it for
Item and stock lookup
get_item and stock_by_warehouse tools reading SB1 and SB2, so any MCP client can answer availability questions with a source.
Sales order status
A tool returning the SC5 header, SC6 items, blocks and linked invoice, replacing a trip through three screens.
Purchase order and receiving history
Tools over SC7 and SD1 showing promised versus received quantities and dates per supplier.
Bill of materials and where-used
Tools over SG1 returning the structure of a product and which parents use a given component.
Open receivables and payables
Read-only views over SE1 and SE2 with due dates and balances, for finance Q&A.
Production order status
A tool over SC2 and the related appointment tables to report quantity produced, scrapped and remaining.
TOTVS Protheus integration surface
- Protheus REST services on the application server (standard FWRest endpoints and custom WsRestFul or TLPP services), where available in your release.
- SQL Server, Oracle or PostgreSQL views over the alias tables, with D_E_L_E_T_ and filial conditions baked in.
- ExecAuto routines such as MATA410 or MATA120 for any later write tools, wrapped in a TLPP service rather than called from outside.
- The SX3 dictionary, used to build tool descriptions with real field titles, including custom ones.
- Existing authentication on REST services (for example basic or token-based) and the Protheus user and permission model.
How it works
- 1
List the questions users actually ask
Interview buyers, planners and the order desk. Turn the top ten questions into tool candidates and drop anything that needs more than a few tables.
- 2
Create views or services per tool
One view or endpoint per tool, parameterized, returning only the needed columns with readable names. Never accept free-form SQL from the model.
- 3
Implement the server
Use the official MCP SDK in Python or TypeScript. Define each tool with a name, description and JSON schema, including mandatory company and branch parameters.
- 4
Choose the transport
stdio for a single developer or desktop use. Streamable HTTP with token auth behind your reverse proxy for shared use across teams.
- 5
Add auth and scoping
Authenticate the client, map it to an allowed set of branches, and apply those filters inside the view call, not in the prompt.
- 6
Log, test and version
Record each call, write regression tests with known orders, and version tool names so clients do not break when a view changes.
- 7
Add proposal tools last
Write tools should create a pending request that a human approves, after which a TLPP routine runs the standard ExecAuto.
Example flows
Availability question from a sales rep
Trigger: Rep asks an MCP client if 200 units of a part can ship Friday.
- Client calls get_item for the part.
- Client calls stock_by_warehouse with the branch.
- Client calls open_po_lines for expected receipts this week.
- Client answers with stock, reserved quantity and incoming supply.
Result: A cited availability answer in seconds, from three small read-only calls.
Planner asks for where-used before changing a component
Trigger: Engineer wants to know which products use component X.
- Client calls where_used with the component code.
- Server queries SG1 recursively up to a set depth.
- Server returns parents and open production orders for each.
Result: The engineer sees the impact of a change before opening an engineering change request.
Keeping data on-prem
Deploy the MCP server on a host inside the same network as the Protheus application server, reach the database through a read-replica or reporting schema, and expose it to clients only through an internal reverse proxy. Pair it with an on-prem MCP client application and an open-weight model served by vLLM or Ollama, so no ERP data leaves. If you also want hosted clients for some users, publish only a restricted subset of tools through a separate gateway instance, so the sensitive tools are never reachable externally.
Security checklist
- Database account: SELECT only, on views, with no access to user, password or payroll tables.
- Require company and branch on every tool and enforce them server-side against the caller's allowed list.
- Use TLS and bearer tokens on the HTTP transport; avoid binding stdio servers to shared shells.
- Return bounded result sizes and redact fields such as CPF and bank details unless explicitly permitted.
- Keep an immutable log of tool name, parameters, caller and row counts for audit.
Ways to get it done
Build in-house with the MCP SDK over existing REST or views
Effort: One to three weeks for a first set of read-only tools.
Good if you have a developer who knows both TLPP and Python or TypeScript.
Use a generic database MCP server with locked-down views
Effort: Days, with extra review before production.
Quick for prototypes, but weaker on branch scoping and tool descriptions.
Have a partner such as Netray design the tool schema and run it
Effort: A scoped pilot over a few weeks.
Fits sites that want a tested server plus private model delivery and monitoring.
Pitfalls
- !Offering a generic run_sql tool. It invites unfiltered cross-branch reads and expensive queries on the transactional database.
- !Forgetting to filter deleted rows, so cancelled orders appear as live.
- !Tool descriptions copied from cryptic field names; the model needs readable titles, especially for custom columns.
- !Mixing read and write tools in the first release, which raises the review burden.
- !No result limits, letting a broad question pull hundreds of thousands of SD1 rows.
Frequently asked questions
What is an MCP server for Protheus?
A small service that exposes named tools, like order status or stock, to AI clients using the Model Context Protocol. Behind the tools it calls Protheus REST services or SQL views. Clients such as Claude can use it without custom code per client.
Does TOTVS provide an official MCP server?
Do not assume so. TOTVS has been investing in AI, but whether an MCP server is available for your product and release should be confirmed with TOTVS. Many teams build a narrow one over their own REST services or views.
Should it use REST or direct SQL?
REST through the application server respects more of Protheus logic and permissions. SQL views are faster to build and good for read-only reporting-style tools. Many sites mix them, but keep SQL access read-only and view-based.
stdio or HTTP transport?
stdio suits a single user running the server locally, such as a developer. For several users, run it as an HTTP service behind a proxy with token authentication, logging and branch scoping so access is controlled centrally.
Which tools should we build first?
Read-only ones with clear value: item and stock lookup, sales and purchase order status, receiving history, bill of materials. They cover common questions, touch few tables, and carry little risk, which makes review and testing straightforward.
Want MCP server working on your TOTVS Protheus?
A free 30 minute assessment: we map the integration path for your version and setup, and where it should run.
Get a free assessment