Mini-ERP MCP — learning project

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.

What it does

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

Concepts this project puts into practice

MCP defines three primitives, and this project uses all three with an explicit design criterion for each:

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.

Architecture

┌───────────────────────┐   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).

Stack

• 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.

How to run it locally

cp .env.example .env   # completar HF_TOKEN (y opcionalmente ANTHROPIC_API_KEY)
uv sync

Test the server in isolation (without LLM)

uv run mcp dev server.py

Open the MCP Inspector in the browser, where you can invoke the tools and read the resources manually.

Run the full flow (host + real LLM)

uv run host_demo.py

By 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.

Environment variables

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_anthropic

What I learned building this

• The 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.

Project status

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).