PNS AI Engine

The pain

AI for your clients as just another module. Open source, no licences. Not a service on the side that you connect client by client. An AI that installs, updates and uninstalls like any other module, on the Odoo the client already runs. Here the agents live in plain Odoo modules.

What you get

Agents that are Odoo

• An agent is a record that a module brings with it. Install the module and the agent is there; uninstall it and it goes.
• Each agent has its own list of providers, in the order you set.
• Everything is in the client's database: no second copy somewhere else.

Providers for each task

• OpenAI and any OpenAI-compatible endpoint, Anthropic, OpenRouter. A local model (Ollama, LM Studio) on the client's own server works too.
• Roles per provider: conversation, audio, vision, video, page layout, turning a phrase into a skill's fields, yes-or-no decisions.
• If one provider fails, the next one in the list answers.
• The key stays in the client's database, never in the module.

A sandbox and a person

• The code the AI writes reads in a read-only transaction, with the rights of the person who asked.
• A change to Odoo is a plan that waits for a person to approve it in Odoo.
• Every call is logged: each user sees their own activity, the administrator sees all of it.
• Outside addresses only from a whitelist you keep.

Knowledge you own

• Contexts: the client's words, rules and habits, edited in Odoo.
• Skills: procedures written once and launched by name. Their tables and charts come from code, not from the AI.
• Export the whole AI setup of one client to a file and import it at the next one.

An MCP server in the client's Odoo

• Cursor and other MCP clients connect to /mcp with a personal key.
• No admin password goes anywhere. Each key reads with its user's rights.
• The client's own model does the thinking; Odoo answers its tool calls. No provider needed for that.

Nothing to license

• Apache 2.0. No fee per user, per database or per year.
• A plain Odoo module: no external server to run.
• Same module at every client on a supported series.

Agents, roles and chains

What an agent is. Anything in Odoo that uses AI: a chat, a voice assistant, an MCP endpoint, a job that runs in the background. In the engine it is a record (AI Engine → Agents) with a code, its contexts, its skills and its list of providers.

The natural home of an agent is the Odoo module that needs it: install the module and the agent is there; uninstall it and it goes. One module can bring more than one. This engine brings two:

• MCP Server (pns_ai_mcp) serves contexts and tools to an outside client such as Cursor. The model runs in that client; Odoo answers its tool calls.
• AI Admin (pns_ai_admin) does the engine's own jobs: writing a skill, reading an API's documentation.

Chatboo brings the chat agent. An agent can also be created by hand in Odoo.

Two kinds. Inference: Odoo calls the model, through the agent's providers (a chat, a voice assistant). Endpoint: the model is outside and Odoo only serves it (MCP).

Roles. A role says what a provider is for. One provider can hold several.

The chain. Each agent has its own providers, in the order you set. When a turn needs a role, the engine takes the providers of that agent that hold it, in that order. If one fails or stalls, the next one answers.

• Each link has its own timeouts: seconds with no data, and seconds for a whole round.
• A provider that holds only that role goes before the ones that do everything: it was chosen for that job.
• If the chain has nobody for a role other than Conversation, the engine looks among every active provider.
• No external failover ends the chain at that provider. Use it on a local model whose data must not go out.
• A key that reached its monthly spend cap is skipped.
• An agent with no chain uses every active provider.

For example: a large model for the conversation, a small one with only Parser, and a local model at the end of the chain as backup.

Included in the module

Read from the module’s own files, version 3.1.931.

Contexts

Example providers

In static/examples/providers/, with no key.

What it does not do

• No chat screen. The engine has no conversation window for users. That is Chatboo.
• No writes on its own. The AI never changes Odoo by itself. Every change is a plan that a person approves in Odoo.
• Four provider protocols. OpenAI-compatible, OpenRouter, Anthropic and SystemOne (yes-or-no decisions). An API that speaks none of them does not connect.
• Two tested series. 14.0 and 19.0. From 15.0 to 18.0 you build the module yourself and try it first; 13.0 and older do not run (see Odoo versions).

Questions

Is it an MCP server? It includes one, in the same module. POST /mcp speaks Streamable HTTP. /mcp/sse with /mcp/message is for clients that only speak SSE. /mcp/<agent> ties the call to one agent. Three tools: relaxaicode (read-only Python against Odoo), safe_plan_request (propose a change) and safe_plan_status (see whether it was approved).

Where do the client's data go? To the providers you set up, and to the outside addresses and API servers you allow. When Cursor or another MCP client connects, its own model sees what the tools return.

Do I need Chatboo? No. The engine alone serves MCP clients. Chatboo adds the chat inside Odoo and brings the engine with it.

What is pns_base? The shared layer of the PNS modules: the same screens load on Odoo 14 and 19, plus small helpers (notifications, import and export, PDF). It installs as a dependency.

Getting started

1. Install. Want the chat too? Install Chatboo instead; it brings this module. For the engine alone, clone the 14.0 or 19.0 branch of pns_base and pns_ai_mcp, add each clone to addons_path and install PNS AI Engine from Apps. On Odoo 14, first run pip install "openpyxl>=3.1.2".
2. Become AI administrator. Settings → Users: give yourself AI Administrator. Log out and back in.
3. Get your API key. AI Engine → Security → Users: your row, tick AI Conversational and press Generate API Key.
4. Add a provider. AI Engine → Connections → Providers: protocol, endpoint, API key and model, with the Conversation role. Or start from a ready one: static/examples/providers/ has OpenRouter, OVH, OpenAI, Anthropic and Lemonade, with no key. Settings → AI Engine → Import configuration, pick the file, then type your key in each provider.

Done. Point Cursor (or any MCP client) at https://<your-odoo>/mcp with the key in the X-MCP-API-Key header. Example below, in Connecting an MCP client.

For IT staff

Connecting an MCP client

In Cursor, add the server to ~/.cursor/mcp.json (all projects) or to .cursor/mcp.json (one project). Other MCP clients take the same two things: the URL and the header.

{
  "mcpServers": {
    "my-client-odoo": {
      "url": "https://odoo.example.com/mcp",
      "headers": {
        "X-MCP-API-Key": "<your-api-key>"
      }
    }
  }
}

The key is the one from step 3 and reads with that user's rights. One key per person; do not commit the file with the key in it.

Repository layout

main is one tree for every series. A flat branch (14.0, 19.0) is that tree built for one series, ready for the addons path.

The installer overlays common/ then the stack; a stack file with the same path wins. Edit agnostic files only in common/. Build a flat module with ./install_flat.sh 19.0 /path/to/addons. Domain UI helpers: utils/mcp_ui.py.

Python: do not add requests or reportlab (Odoo already ships them). pns_base needs no extra pip. On 14, use a current openpyxl (old wheels break with recent NumPy).

Odoo versions

15.0 to 18.0. There is no branch to clone. Build the flat module yourself from main, which has the code for every series (owl2 for 15.0 and later). Do the same for pns_base:

git clone https://github.com/patanegra-soft/pns_base.git
git clone https://github.com/patanegra-soft/pns_ai_mcp.git
cd pns_base   && ./install_flat.sh 17.0 /path/to/addons && cd ..
cd pns_ai_mcp && ./install_flat.sh 17.0 /path/to/addons

The script warns that the series is not tested. Nobody has run the engine on these series, so try it on a test database first and run the Odoo tests there (see Tests). If it works, or does not, tell us (CONTRIBUTING.md).

Odoo 13 has no OWL, which the AI chat is built on. Odoo 8 to 12 run on a Python older than 3.7, which the engine needs. The suite keeps two stacks (owl1 for 14.0, owl2 for 15.0 and later).

Tests

odoo-bin -d <db> -i pns_ai_mcp --test-enable --stop-after-init --test-tags /pns_ai_mcp

License, marks, training

Apache-2.0 — see LICENSE and NOTICE. PATANEGRA Soft™ and PAAP™ (Patanegra Application Agent Protocol, which this engine implements) are trademarks of PATANEGRA Soft SL; the license does not grant them. TDM / AI training is allowed (TDMRep tdm-reservation = 0).

Security: SECURITY.md. Bugs, ideas and questions: CONTRIBUTING.md.