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., "@Mini-ERP MCP What's the current stock level for product 123?"
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.
A Model Context Protocol (MCP) server built on a simulated ERP domain (products, customers, sales), to understand end to end how a language model can discover and use external tools and data in a standardized way, instead of through custom integrations per LLM provider.
Context: this is a personal technical exploration project, not a production product or a client project. The ERP domain is deliberately minimal (a JSON file as the "database") — the goal is not business logic, but understanding the protocol.
It simulates the flow of an incoming message (for example, from WhatsApp) that arrives at an ERP-like system. The system assembles the relevant context for the model, offers it a set of tools, and the model autonomously decides which action to take to respond — including an action with a real effect (recording a sale), which requires human confirmation before being executed.
Related MCP server: OdooSurface MCP
MCP defines three primitives, and this project uses all three with an explicit design criterion for each:
Element | Type | Why |
| Resource | Stable data; the inbound host decides to inject it, without the model asking for it. |
| Resource (URI with parameter) | The host already knows the ID of the sender (it would come from the webhook); it builds the URI and injects it. |
| Tool | The model decides, in the middle of the conversation, whether it needs it. |
| Destructive tool | Action with a real effect; requires human confirmation before being executed. |
| Prompt | Reusable template for a recurring task. |
The central distinction this project lets you verify in practice: with a tool, the host hands the model the decision to invoke it; with a resource, the host keeps that decision for itself.
┌───────────────────────┐ stdio ┌───────────────────────┐
│ Host (host_demo.py) │◄────────►│ Servidor MCP │
│ - Arma el contexto │ │ (server.py, FastMCP) │
│ - Ofrece tools al LLM │ │ - Resources │
│ - Ejecuta el loop de │ │ - Tools │──► data/erp.json
│ tool-calling │ │ - Prompts │
│ - Pide confirmación │ └───────────────────────┘
│ humana en acciones │
│ destructivas │
└──────────┬────────────────┘
│ API compatible OpenAI (router de HF) o API de Anthropic
▼
┌─────────────┐
│ LLM │
└─────────────┘host_demo.py plays, in this project, both the role of host and MCP client (in a real integration, the MCP client is usually a module inside the host, not a separate piece).
mcp[cli] (FastMCP) — official Python SDK for MCP servers.
Hugging Face Inference Providers — open source models, via the OpenAI API-compatible router (openai SDK pointing to https://router.huggingface.co/v1).
Anthropic SDK — alternative support, maintained in parallel to compare the same MCP server working with two different providers.
MCP Inspector — development tool for testing the server without needing a real client.
cp .env.example .env # completar HF_TOKEN (y opcionalmente ANTHROPIC_API_KEY)
uv syncuv run mcp dev server.pyOpen the MCP Inspector in the browser, where you can invoke the tools and read the resources manually.
uv run host_demo.pyBy default it uses Hugging Face (procesar_mensaje_huggingface). The code for using Anthropic (procesar_mensaje) remains available in the same file, commented out in the if __name__ == "__main__": block.
HF_TOKEN=tu_token_de_huggingface
HF_MODEL=openai/gpt-oss-120b
# Opcional, si se quiere probar con Anthropic en vez de Hugging Face
ANTHROPIC_API_KEY=tu_api_key_de_anthropicThe real mechanism for discovering and invoking tools in MCP: the model never talks directly to the MCP server; the host mediates every list_tools() / call_tool() / read_resource().
The difference between native function calling in each LLM provider (different formats between Anthropic and OpenAI-compatible APIs) and how MCP standardizes the exposure of tools without depending on those particular formats.
That not all models served by an inference provider support tool-calling reliably, and how to verify it before integrating.
Where the responsibility for human control over actions with effects lies (it is not something the protocol resolves automatically; it is a host design decision).
Real portability: the same server.py, without modifications, works the same with two different LLM providers.
Learning project, complete and functional for the defined scope. Pending as a possible future extension: connecting the same server to Claude Desktop to verify portability against a real client (not just the host_demo.py script).
Consulta el stock disponible de un producto específico por su ID.
Usar esta herramienta cuando el cliente pregunte por disponibilidad de un producto puntual.
| Name | Required | Description | Default |
|---|---|---|---|
| producto_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a safe read operation via 'Consulta', but says nothing about behavior when the product ID is unknown, the stock format, or any limits. Minimal but adequate for a simple read 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?
Two short sentences, purpose front-loaded ahead of the usage condition, with no wasted wording. Appropriately sized for the tool's simplicity.
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?
An output schema exists, so return values need not be explained. For a single-parameter read tool, purpose and when-to-use cover the essentials; only edge-case behavior (unknown ID) is left unstated.
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 coverage is 0% for the single required parameter. The phrase 'por su ID' clarifies that producto_id is an identifier rather than a name, adding some meaning, but no format or validity details are given.
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 (Consulta) and resource (stock disponible) scoped to a single product by ID, so the agent immediately knows what it does. The purpose is functionally distinct from the sibling registrar_venta, though the description never explicitly contrasts them.
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 second sentence gives a clear triggering condition: use when the customer asks about the availability of a specific product. It offers no explicit exclusions or named alternatives, which is the only gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Registra una venta: descuenta stock y crea el registro de la operación.
ACCIÓN CON EFECTO REAL sobre el estado del sistema. Usar solo cuando
el cliente confirmó explícitamente que quiere comprar.
| Name | Required | Description | Default |
|---|---|---|---|
| cantidad | Yes | ||
| cliente_id | Yes | ||
| producto_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, and the description usefully adds what actually changes: stock is decremented and an operation record is created. It does not cover reversibility, permission requirements, or failure modes such as insufficient stock, which is the remaining gap.
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?
Short and front-loaded: the action and its effects come first, then the usage guardrail. The capitalised warning line is deliberate emphasis rather than filler, though it partially restates the destructive annotation.
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?
An output schema exists, so return values need no explanation, and the mutation's effect on state is described. However, an irreversible write tool with 0% parameter documentation and no auth, stock-check, or error guidance is only minimally 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 0% and the description adds no information about the three required parameters. Their names (cliente_id, producto_id, cantidad) are self-explanatory, but no format, ID source, or unit/limit semantics are given, so the description fails to compensate for the coverage gap.
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 (registra) and resource (una venta) plus the two concrete side effects: descuenta stock and crea el registro de la operación. That side-effect profile cleanly separates it from the read-only sibling consultar_stock, though it never names that sibling explicitly.
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?
Gives an explicit gating condition: use only when the customer has explicitly confirmed they want to buy. That is a clear when-to-use rule, but no alternative tool or when-not-to-use path (e.g. first check stock via consultar_stock) is named.
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.
v0.1.0consultar_stockregistrar_ventaScored across 2 tools
The two tools are unambiguously distinct: consultar_stock is a read-only stock lookup and registrar_venta is a state-changing sale registration. Descriptions explicitly frame the boundary (read vs. real-effect write), so an agent cannot confuse them.
Both names follow the same Spanish verb_noun pattern (consultar_stock, registrar_venta) with consistent snake_case and imperative verbs. There is no mixed convention.
Two tools is far too thin for a server scoped as a 'Mini-ERP' handling inventory and sales; even a minimal ERP needs product listing, restock/adjustment, and sales history. The surface only covers a single narrow checkout flow.
Only a read-stock plus create-sale pair exists, with no product catalog/listing, no inventory update or restock, no sale retrieval or cancellation, and no reporting. Agents will hit dead ends for any operation beyond checking one product and recording one sale.
Odoo ERP for AI agents: hosted OAuth endpoint, gated writes, one endpoint for every instance.
Give AI agents 30,000+ safe, token-optimized actions across Workday, SAP, Oracle + hundreds more.
Malaysian SME accounting, e-Invoice and payroll for your AI. 64 tools; writes are approved drafts.
OPC Suite — CRM, sales, inventory, accounting, HRM, payroll, claims, projects from any AI agent.
