How to build an MCP server for Epicor Prophet 21
Short answer
An MCP server for Prophet 21 is a small service that publishes a handful of read-only tools, such as item lookup, order status and inventory by location, backed by SQL Server views or the P21 API. Any MCP client, including Claude and ChatGPT-compatible tools, can then call it with scoped permissions and an audit trail.
Model Context Protocol is a standard way for an AI client to discover and call tools. Instead of writing a different integration for each assistant, you write one server that describes what it can do: tool names, parameters, and what comes back. Clients that speak MCP can then use it without custom glue.
For Prophet 21 that is attractive because the integration work is the same whichever assistant your staff end up using. The server sits between the model and P21, and it is the right place to enforce what is allowed: which tables, which columns, how many rows, which user.
This page is about designing that server well: the first tools to build, how to authenticate to P21, how to run it, and the mistakes that turn a neat demo into a security problem.
What teams use it for
Item master lookup
Tools like search_items and get_item return description, unit of measure, product group, supplier, alternates and cross-references. This is the foundation most other questions depend on.
Availability by location
get_availability returns on-hand, allocated, on-order and available by distribution center, with next receipt dates. Counter staff stop switching between inventory windows.
Order and shipment status
get_order and get_shipments return header, lines, pick and ship status, tracking numbers and backordered quantities for a sales order or customer PO.
Customer pricing lookup
get_price_for_customer resolves the price a given customer would get for an item and quantity, ideally by calling P21's pricing logic rather than reproducing it in SQL.
Purchasing visibility
list_open_pos and get_supplier_performance give buyers receipts, due dates, late lines and lead time history, restricted to purchasing roles.
Draft document creation
A later-phase create_draft_quote or create_draft_po tool writes through the P21 API in a draft state, returning an ID for a human to open and finish.
Epicor Prophet 21 integration surface
- SQL Server read path: curated views and a dedicated read-only login, ideally against a replica. Fast to build, but you must reproduce any business logic in SQL, which is risky for pricing and allocation.
- P21 Interactive and Transaction API: supported route for operations that need application logic, such as price resolution or document creation. Endpoint names, authentication and availability vary by version and licensing.
- P21 OData or data service style endpoints in newer releases: potentially simpler reads than raw SQL while respecting security. Verify what your build includes.
- P21 users and roles: the application has its own security model. A server that connects with one all-powerful account bypasses it, so map MCP users to P21 identities or restrict tools by role.
- Network placement: P21 databases are normally on internal servers, so the MCP server runs on the same network and is reached via VPN, reverse proxy or a local client process.
How it works
- 1
List the read tools first
Start with four to eight tools that answer real questions. Fewer, well described tools beat dozens of overlapping ones, because the model selects among them by description.
- 2
Pick an SDK and language
Official MCP SDKs exist for TypeScript and Python among others. Use whatever your team can maintain, and a SQL Server driver or HTTP client for the P21 API.
- 3
Write each tool as a typed function
Define input schemas with strict types and limits, for example item_id as a string with a maximum length and a row limit capped at 50. Use parameterized queries only, never string concatenation.
- 4
Choose the transport
Use stdio when each user runs the server locally with their own credentials. Use streamable HTTP when one shared server serves many clients, with authentication in front of it.
- 5
Add authorization
Resolve the caller to a P21 user or role, then filter or deny tools accordingly. Cost, margin and customer-specific pricing are the fields most worth gating.
- 6
Add audit logging and rate limits
Log caller, tool, arguments, duration and row count to a store the AI client cannot alter. Limit calls per minute to stop runaway loops.
- 7
Test with more than one client
Try the server from Claude Desktop, another MCP-capable client and a script. Tool descriptions that work in one can confuse another, and testing exposes it.
Example flows
Availability question from any client
Trigger: A user asks an MCP-enabled assistant whether 3/4 inch black pipe nipples are in stock in the Dallas branch.
- The client calls search_items with the description and gets candidate item IDs.
- It calls get_availability for the best match and location.
- The server returns on-hand, allocated, available and next receipt.
Result: The user gets a precise answer and the audit log shows exactly which two calls produced it.
Customer-specific price check
Trigger: A salesperson asks what a contractor customer pays for a given item at quantity 200.
- The assistant calls get_price_for_customer with customer, item and quantity.
- The server calls the P21 pricing capability and returns price, source (contract, book, multiplier) and break.
- The server checks the caller's role and omits cost and margin for non-privileged users.
Result: The salesperson sees the price and its source, and never sees cost they are not entitled to.
Draft quote for review
Trigger: An approved user asks the assistant to start a quote for a list of items.
- The assistant resolves items and availability with read tools.
- It calls create_draft_quote with customer and lines.
- The server writes through the API in a draft state and returns the quote number.
Result: A salesperson opens the draft in P21 and finishes it, so the system of record is still driven by a person.
Keeping data on-prem
An MCP server is naturally on-prem friendly because it is just a process you run next to P21. Deploy it on a Windows or Linux host inside the network, connect it to SQL Server or the P21 API over internal addresses, and point clients at it over the corporate network or VPN. The model itself can be hosted or local: the server does not care. If data must not go to a cloud model, run an open-weight model on your own GPU and use an MCP-capable client or agent framework against it. For a P21 instance hosted by Epicor, direct SQL may be unavailable, so build the server on the supported APIs and run it in a place that can reach them.
Security checklist
- Enforce read-only at the database with a login that has SELECT on named views only. Do not rely on the tool code to stay safe.
- Use parameterized queries and strict input schemas to prevent injection through model-generated arguments.
- Authenticate every caller, apply per-role tool and field filtering, and refuse requests that exceed row limits.
- Treat tool descriptions and returned data as untrusted content. Text inside an item note or customer comment can contain instructions meant to manipulate the model, so do not return free-text fields to write-capable agents without care.
- Log all calls immutably, and alert on unusual volume or access to sensitive fields.
Ways to get it done
Generic database MCP server
Effort: Hours to configure, but harden before real use.
Quick for prototypes if it can be locked to specific views. Poor at business logic like pricing and allocation.
Custom MCP server over views and the P21 API
Effort: One to three weeks for a solid read-only set, longer for write tools.
Best long-term for most distributors. You decide tools, fields and permissions, and can call application logic.
Partner-built server with governance
Effort: A scoped project, usually several weeks.
Suitable when you want audit, role mapping, evaluation sets and a private model alongside the server, as Netray provides.
Pitfalls
- !A single generic query tool with broad credentials. It is flexible, but it makes data control and cost impossible to guarantee.
- !Re-implementing pricing or availability in SQL. Results will differ from what the P21 screen shows and erode trust. Call the application where logic matters.
- !Returning free-text notes and descriptions unfiltered, which can carry injected instructions or sensitive remarks.
- !No row caps, so a model loop pulls a whole order history and exhausts context or leaks more than intended.
- !Forgetting version drift. After a P21 upgrade, column names or API behavior may change, so keep integration tests that run against a test environment.
Frequently asked questions
Does Epicor provide an MCP server for Prophet 21?
Do not plan on it without checking. Vendors are adding AI features, but an MCP server for your specific version may not exist. Building a small one is realistic because the protocol is simple and the P21 data and API surface is well understood by integrators.
Which language should I use?
TypeScript and Python both have official SDKs and mature SQL Server drivers. Choose the one your team already operates. The language matters less than the discipline: typed inputs, parameterized queries, narrow credentials and logging.
Should it write to Prophet 21?
Start with reads. When you add writes, use the supported API, create documents in draft or hold state, and require a person to release them. Keep write tools in a separate server or role so a read-only deployment cannot be escalated by accident.
stdio or HTTP transport?
Use stdio when each person runs the server on their own machine under their own credentials, which gives natural user scoping. Use HTTP when you want one managed server for many users, but add authentication, TLS and per-user authorization in front of it.
Will it work with ChatGPT as well as Claude?
MCP is an open protocol with growing client support, including Claude and other tools, and OpenAI products have added MCP support in some surfaces. Client support varies by plan and changes quickly, so test the clients you intend to use rather than assuming parity.
Want MCP server working on your Epicor Prophet 21?
A free 30 minute assessment: we map the integration path for your version and setup, and where it should run.
Get a free assessment