How to build an MCP server for Katana
Short answer
A Katana MCP server is a small service that exposes Katana REST API calls as typed tools to any MCP client such as Claude or ChatGPT. Start with read-only tools for items, stock, sales orders, manufacturing orders and purchase orders, add caching for the rate limit, and log every call.
The Model Context Protocol lets an AI client discover tools and call them with structured arguments. For Katana that means a planner can ask a question in Claude or another client and the client calls get_stock or get_open_purchase_orders rather than guessing from memory.
Because Katana is a hosted API product, an MCP server is mostly an adapter: translate tool calls to REST requests, shape the responses and enforce your rules. The design choices that matter are which tools exist, how you authenticate, and how you stop one enthusiastic client from burning the rate limit.
What teams use it for
Item and variant lookup
Find a product or variant by SKU or name fragment, returning unit of measure, default supplier and current stock.
Order status for sales and support
Return sales order status, rows and linked manufacturing order progress so customer service can answer without opening Katana.
Open purchase order view
List open POs by supplier or material with expected dates to answer when something arrives.
Recipe explosion
Return the ingredient list for a variant, one level or flattened, with current availability per ingredient.
Capacity and schedule peek
Show manufacturing orders and operations due in a date range so planners can ask what is on for next week.
Shared tooling across clients
One server serves Claude Desktop, ChatGPT apps that support MCP and your own agents, so you maintain the Katana logic once.
Katana integration surface
- Katana REST API with bearer API key; the server holds the key and never returns it to clients.
- Resource endpoints for products, variants, materials, recipes, sales orders, manufacturing orders, purchase orders, stock and locations. Verify exact paths and filter parameters against current Katana docs, since they evolve.
- Pagination on list endpoints, which the server must follow or expose as cursor parameters.
- Webhook support if you want the server to refresh a local cache on change events.
- Per-key rate limits that a shared server must respect with a queue, backoff and caching.
How it works
- 1
Pick an SDK and transport
Use an official MCP SDK in TypeScript or Python. Stdio transport suits a personal tool launched by Claude Desktop. Streamable HTTP suits a shared team server behind authentication.
- 2
Define a read-only tool set
Name tools by intent: search_items, get_stock, get_sales_order, list_manufacturing_orders, list_open_purchase_orders, get_recipe. Each takes few, well described arguments.
- 3
Shape responses
Return compact JSON with the fields people use, plus ids so a follow-up call is possible. Drop audit noise and large nested blobs.
- 4
Add caching and throttling
Cache catalogue data for minutes to hours, cache stock briefly, and queue calls so a burst stays under the rate limit.
- 5
Authenticate clients
For HTTP, require OAuth or a token tied to a person or team, and map that identity to allowed tools.
- 6
Log and test
Write each call with caller, tool, arguments and result size. Test with a client against a Katana sandbox or a low-risk account first.
Example flows
Customer service status check
Trigger: Support user asks the assistant for the status of a sales order
- Client calls get_sales_order with the order number.
- Server fetches the order and its rows from the API.
- Server adds linked manufacturing order status.
- Client summarises status and expected ship timing.
Result: An accurate answer without giving support staff full Katana access.
Planner asks what is short
Trigger: Planner prompts a client with the next seven days of builds
- Client calls list_manufacturing_orders for the date range.
- For each variant it calls get_recipe and get_stock.
- Server serves repeated catalogue calls from cache.
- Client lists shortages and open PO coverage.
Result: A shortage list that stays within rate limits through caching.
Keeping data on-prem
Katana has no on-prem option, but the MCP server can run wherever you choose: a laptop for one user, a VM in your network, or a private cloud. Hosting it yourself keeps the Katana API key, the cache and the audit log in your environment, and lets you pair it with an open-weight model so no third party model sees the data. Make sure outbound access to the Katana API is allowed from that network, and note that inbound webhooks need a public HTTPS path or a relay you control.
Security checklist
- Keep the Katana API key in a secrets manager and rotate it; never place it in client configuration.
- Expose read tools only at first; add write tools as separate, clearly named draft operations.
- Authenticate HTTP clients and scope tools per role, for example no cost fields for support users.
- Validate every argument and reject unexpected fields before calling Katana.
- Audit log each call with identity, tool, arguments and timestamp.
Ways to get it done
Community MCP server for Katana, if one exists
Effort: Hours
Quick trial. Review the code, scope and maintenance before trusting it with a production key.
Build your own with an MCP SDK
Effort: One to three weeks
You need control over fields, caching and permissions.
Netray builds and runs it
Effort: A scoped project
You want a hardened server with roles, audit and optional private model hosting.
Pitfalls
- !Mirroring every API endpoint as a tool, which overwhelms the model and widens the attack surface.
- !Skipping pagination so lists silently truncate.
- !No caching, which exhausts the rate limit as soon as two people use it.
- !Returning cost and margin fields to roles that should not see them.
- !Letting the model pass free-form filters straight into the API without validation.
Frequently asked questions
What is an MCP server for Katana?
It is a service that translates Model Context Protocol tool calls into Katana REST API requests. Any MCP client, including Claude and compatible ChatGPT apps, can then look up stock, orders and purchase orders through consistent, typed tools.
Stdio or HTTP transport?
Use stdio for a single user running the server locally, which is easy and keeps credentials on their machine. Use HTTP for a shared team server so you can centralise the API key, add authentication, caching and audit logging.
Which Katana tools should I expose first?
Start with item search, stock by location, sales order detail, manufacturing order list, open purchase orders and recipe lookup. These answer most daily questions with no write risk. Add draft write tools later, behind human approval.
How do I deal with rate limits?
Cache catalogue data, cache stock for short periods, queue outbound requests, and use backoff on limit responses. Check Katana's current documented limits, and keep tool responses small so the model does not trigger follow-up calls unnecessarily.
Does it work with both Claude and ChatGPT?
Yes for clients that support MCP, though the exact setup differs by client and plan. The server logic stays the same, which is the main reason to build it once as MCP rather than separately for each assistant.
Want MCP server working on your Katana?
A free 30 minute assessment: we map the integration path for your version and setup, and where it should run.
Get a free assessment