Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@patagon-inventory-mcp how many safety helmets are left in stock, and are any below minimum?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server that lets an AI agent manage inventory through natural language — check stock, register entries and exits, and flag low-stock items — without ever inventing a number.
It is a small, open-source extraction of patterns I use in production at Patagon, a B2B platform where AI agents run day-to-day operations for SMBs over WhatsApp. It uses sample data only.
"Se gastaron 10 cascos en la faena norte" → the agent calls
register_movement→ stock goes 38 → 28, and if the same WhatsApp message is delivered twice, it is still counted once.
When an LLM manages real inventory, three things go wrong:
Problem | How this server handles it |
The model hallucinates stock figures | Every number comes from a tool. Tool descriptions and the |
Messages get retried or duplicated (webhooks, flaky networks) |
|
The model claims success when something failed | Invalid operations return an explicit MCP tool error ( |
Related MCP server: Korral StoreLink MCP
flowchart LR
U[User on WhatsApp / chat] --> H[MCP host<br/>Claude Desktop, Claude Code,<br/>or a custom agent]
H <-->|MCP over stdio| S[patagon-inventory-mcp]
S --> T[Tools]
S --> R[Resources]
S --> P[Prompts]
T & R --> D[(InventoryStore<br/>domain logic)]The domain logic (src/inventory.ts) knows nothing about MCP, so it can be unit-tested in isolation and
reused behind any transport. src/server.ts is a thin MCP layer on top of it.
Tools (model-controlled)
Tool | Description |
| List products, optionally filtered by SKU or name |
| Current stock of one product, with status |
| Register an |
| Products below their minimum, with units missing |
| Recent movements, newest first |
Tools carry MCP annotations (readOnlyHint, idempotentHint) so hosts can decide which calls need user confirmation.
Resources (application-controlled)
inventory://products — full catalog snapshot
inventory://products/{sku} — resource template with listing and SKU autocompletion
Prompts (user-controlled)
stock_report — a reusable, tested instruction for a short team report, grounded in tool data
Requires Node.js 22+.
git clone https://github.com/Sr-Stark08/patagon-inventory-mcp.git
cd patagon-inventory-mcp
npm install
npm run buildnpm run inspectAdd this to your claude_desktop_config.json:
{
"mcpServers": {
"patagon-inventory": {
"command": "node",
"args": ["/absolute/path/to/patagon-inventory-mcp/dist/index.js"]
}
}
}claude mcp add patagon-inventory -- node /absolute/path/to/patagon-inventory-mcp/dist/index.jsdocker build -t patagon-inventory-mcp .
docker run -i --rm patagon-inventory-mcpnpm testUnit tests for the domain rules: idempotency, key conflicts, no negative stock, input validation, minimum-stock crossing.
End-to-end tests that connect a real MCP Client to the server over an in-memory transport and exercise
tools, resource templates and prompts through the protocol.
CI (GitHub Actions) runs type-checking, tests and the build on Node 22 and 24, then builds the Docker image and smoke-tests it over stdio.
src/
inventory.ts # domain logic: products, movements, idempotency, validation
server.ts # MCP layer: tools, resources, prompts
index.ts # stdio entry point
tests/
inventory.test.ts
server.test.tsData is in memory with sample products; a restart resets it. The store is isolated so it can be swapped for PostgreSQL or SQLite without touching the MCP layer.
Only the stdio transport is wired up. A Streamable HTTP entry point would enable remote deployments.
No authentication — intended for local use by an MCP host.
Jorge Fraile Pereira — AI Agent Developer, founder of Patagon. Anthropic Academy: Building with the Claude API · Model Context Protocol (Intro & Advanced) · Claude Code in Action.
License: MIT
Most recent stock movements, newest first. Optionally filter by SKU.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | No | Filter by product SKU | |
| limit | No | Max movements to return (default 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read, lowering the disclosure burden. The description adds the sort order (newest first) and that SKU filtering is optional, both genuinely useful traits beyond the annotations, but says nothing about pagination behavior or result size beyond what the schema's limit already encodes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler, and the core behavior (most recent movements, newest first) is front-loaded ahead of the optional filter detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only, two-parameter list tool with full schema coverage and no output schema, the description covers purpose, ordering, and the optional filter adequately. Only a brief note on result volume or truncation behavior would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (sku, limit) are already documented in the schema, and the baseline is 3. The description's "Optionally filter by SKU" only restates the schema rather than adding syntax, format, or edge-case meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Most recent stock movements") plus the ordering ("newest first"), which an agent can distinguish from get_stock or list_low_stock. It does not explicitly name a sibling alternative, but the scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Optionally filter by SKU" implies that unfiltered retrieval is the default path and filtering is the narrow case, which is reasonable usage guidance. There is no explicit statement of when to prefer this over get_stock or list_low_stock, so guidance remains implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current stock of one product by SKU. Always use this before telling a user how much stock there is — never guess.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | Yes | Product SKU, e.g. EPP-CASCO |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint=true annotation already tells the agent this is a safe, non-mutating read, so the description's job is lighter. It adds the useful behavioral rule that stock must be fetched rather than inferred, but says nothing about what happens for an unknown SKU or what the returned value looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, both front-loaded: the capability first, then the operating rule. Every clause earns its place with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description is the only source for return-value expectations, and it leaves the response shape (a raw quantity vs. a stock object) and missing-SKU behavior unspecified. For a single-parameter read tool this is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and there is only one parameter, so the schema already carries the semantics fully (SKU with an example, EPP-CASCO). The description only restates 'by SKU' and adds no format or lookup nuance, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Get the current stock') and narrows scope to 'one product by SKU', which cleanly separates it from sibling listing tools like list_products and list_low_stock. It does not name those siblings explicitly, so it falls just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Always use this before telling a user how much stock there is — never guess' gives an explicit when-to-use trigger plus a prohibition, which is stronger than typical usage guidance. It does not, however, mention alternatives (e.g. use list_low_stock when you need many products at once), so it stops short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List products whose stock is below their configured minimum.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already declares the safety profile, so the description only needs to add context. It contributes the notion of a per-product configured minimum (the threshold semantics), but says nothing about ordering, pagination, limits, or how products without a configured minimum are treated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with zero filler, front-loading the verb and the narrowing condition. Nothing to trim.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool with no output schema and annotations covering safety, the description is sufficient to invoke correctly. It only misses edge-case behavior such as products with no configured minimum or result ordering.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4. There is no argument syntax the description could clarify, and it correctly avoids inventing any.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') plus resource ('products') and a precise filter criterion ('stock below their configured minimum'), which cleanly separates it from the sibling list_products. It does not explicitly name the sibling, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The threshold criterion strongly implies the use case (surfacing items needing restocking), but the description never states when to prefer this over list_products/get_stock or any exclusions. Usage is implied rather than guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List inventory products, optionally filtered by a text query that matches SKU or name.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Text to search in SKU or product name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes this as a safe read, so the description's burden is lower. It usefully adds that the query matches SKU or name, but says nothing about result size, ordering, or pagination behavior, which matters for a listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the core action and the optional modifier trailing it. Every clause earns its place with no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool with readOnlyHint and no output schema, the description covers what is needed to invoke it correctly. The only real gap is sibling disambiguation, which is minor given how little this tool needs to explain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter is fully documented in the schema, so the baseline is 3. The description's 'matches SKU or name' largely restates the schema's own parameter description rather than extending it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (List) and resource (inventory products) with the filtering scope, so the operation is unambiguous. It does not, however, distinguish itself from the sibling list_low_stock, which is also a product-listing tool, so an agent gets no help choosing between the two from the text alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies when the tool applies by noting the filter is optional, which tells the agent it can call this with no arguments for a full listing. It names no alternatives and gives no explicit when-to-use versus get_stock or list_low_stock guidance, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register a stock entry (in) or exit (out). Idempotent: send the same idempotency_key when retrying so the movement is never counted twice.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | Yes | Product SKU | |
| note | No | Optional context, e.g. 'north site crew' | |
| type | Yes | 'in' adds stock, 'out' removes stock | |
| quantity | Yes | Whole number of units | |
| idempotency_key | Yes | Unique key for this real-world movement, e.g. the chat message ID. Reuse it only for retries. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, so the safety and dedup profile is known without the description. The description does add a practical detail – reuse the key only for retries, not for new movements – which is genuinely useful context beyond the annotation. It says nothing about what happens on a rejected/duplicate call or any authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, no filler. The core purpose is front-loaded and the idempotency caveat follows immediately, which is exactly the right ordering for a mutation tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, direction, and the idempotency contract for a 5-parameter write tool whose schema is fully documented and whose annotations carry the safety profile. With no output schema, return values needn't be explained, but the description is silent on failure/duplicate-key behavior and on whether 'out' quantities are validated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including an explicit explanation of idempotency_key and the in/out enum, so the schema already carries the parameter meaning. The description restates the in/out semantics and key reuse rather than adding new syntax or constraints, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (register) and resource (stock movement) plus the two directional modes (in/out), which maps directly onto the 'type' enum. It doesn't name or contrast with the sibling read tools (get_stock, get_movement_history), but the write-vs-read distinction is obvious from the verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides real guidance for the retry case ('send the same idempotency_key when retrying'), which is the main usage pitfall for a movement-recording call. It says nothing about when to prefer this tool over siblings or any preconditions such as stock availability for 'out'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_movement_historyget_stocklist_low_stocklist_productsregister_movementScored across 5 tools
Each tool has a distinct purpose: list_products (catalog browsing), get_stock (single SKU stock), list_low_stock (filtered subset), register_movement (writes), and get_movement_history (audit trail). The overlap between list_products and list_low_stock is clearly differentiated by the minimum-threshold filter, and get_stock is explicitly scoped to a single SKU.
All five tools follow a uniform verb_noun snake_case pattern (list_products, get_stock, register_movement, list_low_stock, get_movement_history). Verbs are meaningful and consistent across the set.
Five tools is well-scoped for a focused inventory server, and each one covers a distinct read or write operation without redundancy. Nothing feels padded or missing at the count level.
Core inventory lifecycle is covered: browse catalog, check stock, record in/out movements idempotently, surface low stock, and review history. Minor gaps exist around product creation/updating and configuring minimum thresholds, but these are workable around and don't block main workflows.
Hosted MCP for e-commerce: live product catalog, stock, and pricing for AI agents.
See, price, and control every tool call your AI agents make: policy checks, cost, and audit tools.
Give your AI agents the tools to build, manage, and run automation workflows.
Store, query, and update structured data from any AI agent
