# Connecting an AI Agent to Odoo: External API, MCP and Permissions

> An AI agent talks to Odoo through its External API: the /json/2 endpoint with an API key from Odoo 19 onwards, XML-RPC or JSON-RPC on older versions. It runs as a dedicated bot user whose access rights and record rules decide what it can read and change. An MCP server can expose those calls as tools.

Canonical URL: https://www.ruebstudio.de/en/guides/ai-agent-integrations/connect-ai-agent-odoo  
Author: Dr.-Ing. Marcus Rüb, CEO  
Published: 2026-11-08

Odoo is an open-core ERP that runs sales, purchasing, inventory, accounting and helpdesk in a single database. That makes it a convenient target for an AI agent: the customer, the quote, the stock level and the unpaid invoice all live in one data model behind one API. This guide covers which API to use on which Odoo version, how the data model looks from an agent's point of view, and how Odoo's permission system keeps the agent inside its lane. Everything here is based on the Odoo 19 documentation as of November 2026.

## What does connecting an AI agent to Odoo involve?

Connecting an agent to Odoo means giving a language model a small set of tools that search and read Odoo records and, in narrowly defined cases, create or update them. Under the hood each tool calls a method on an Odoo model through the External API, authenticated as a dedicated user with its own permissions.

Common jobs for such an agent:

- **Drafting quotations:** read the customer, pricelist and products, then create a draft `sale.order` for a salesperson to review and send.
- **Answering "where is my order?":** look up the sales order and its delivery, and reply without anyone opening the inventory app.
- **Triage of inbound email:** match the sender to a contact, open a CRM lead and pre-fill the key details.
- **Account briefings:** summarise open invoices, recent tickets and running orders before a customer call.

The general patterns behind this kind of work, such as reading before writing, human approval steps and audit logging, are covered in the [complete guide to connecting AI agents to business systems](https://www.ruebstudio.de/en/guides/ai-agent-integrations/connect-ai-agents-to-business-systems). This article focuses on what is specific to Odoo.

## Which APIs does Odoo offer for AI agents?

Since version 19, Odoo exposes the External JSON-2 API at `/json/2/<model>/<method>`, authenticated with an API key sent as a bearer token. The older XML-RPC and JSON-RPC APIs still work but, according to the [RPC API reference](https://www.odoo.com/documentation/19.0/developer/reference/external_rpc_api.html), they are deprecated since 19.0 and scheduled for removal in Odoo 22 (autumn 2028).

### The JSON-2 API (Odoo 19 and later)

The [JSON-2 API reference](https://www.odoo.com/documentation/19.0/developer/reference/external_api.html) describes a simple contract. You POST a JSON body to `/json/2/<model>/<method>`. The `Authorization` header carries `bearer` plus the API key, and an optional `X-Odoo-Database` header selects the database when one server hosts several. The body holds the record ids, an optional `context` and the method's parameters by name. Errors come back as a 4xx or 5xx status with a JSON object naming the Python exception and its message.

That shape maps neatly onto agent tool calling: one tool, one HTTP request, one JSON result that can go straight back to the model.

### XML-RPC and JSON-RPC (up to Odoo 18, deprecated in 19)

The legacy RPC API offers three services: `common`, `db` and `object`. You call `authenticate` to get a user id, then invoke model methods through `execute_kw`, passing the database, user id and password or API key on every call. The documentation notes that with RPC you simply use the API key in place of the password while keeping the login.

If you run Odoo 17 or 18, RPC is your only option. Hide it behind a thin client module of your own so that moving to JSON-2 later touches one file, not every tool. Note that the removal date for Odoo Online is earlier: version 21.1, planned for winter 2027.

### Your database documents itself

Which models, fields and methods exist depends on the apps and custom modules installed. The JSON-2 reference points to each database's `/doc` page, which lists the schema that is actually available there. When designing tools, that page is more useful than any generic tutorial because it includes your own custom fields.

## How is the Odoo data model structured?

Odoo stores everything in models with technical names such as `res.partner` for contacts, `sale.order` for quotations and orders, and `product.product` for product variants. Each model has fields and methods. In practice an agent mostly needs the standard ORM methods `search`, `read`, `search_read`, `create` and `write`, plus a few business methods.

Design consequences for agent tools:

- **Domains belong in code.** Odoo filters are lists of conditions such as `[["is_company", "=", true], ["name", "ilike", "%smith%"]]`. Do not ask the model to write them; give it a `find_customer(name)` tool and build the domain yourself.
- **Always name the fields.** Without a `fields` list, `read` returns a large number of fields. That wastes context and can expose data the agent has no reason to see.
- **Flatten relations.** Fields like `partner_id` or `order_line` point to other models. A good tool resolves what the model needs and returns a flat structure rather than raw id lists.
- **Prefer business methods to field edits.** Many models offer methods prefixed with `action_`, such as `action_confirm` on `sale.order`, which validate the record before changing its state. Use those instead of writing the `state` field directly.

A minimal read tool in Python, following the request format in the Odoo 19 documentation:

```python
import os
import requests

BASE_URL = os.environ["ODOO_URL"] + "/json/2"
HEADERS = {
    "Authorization": f"bearer {os.environ['ODOO_API_KEY']}",
    "X-Odoo-Database": os.environ["ODOO_DB"],
    "User-Agent": "odoo-ai-agent",
}

def find_customer(name: str, limit: int = 5) -> list[dict]:
    """Agent tool: look up company contacts by name."""
    res = requests.post(
        f"{BASE_URL}/res.partner/search_read",
        headers=HEADERS,
        json={
            "domain": [["is_company", "=", True], ["name", "ilike", name]],
            "fields": ["name", "city", "email"],
            "limit": limit,
        },
        timeout=30,
    )
    res.raise_for_status()
    return res.json()
```

It uses `search_read` rather than a `search` followed by a `read`. The section on transactions below explains why that matters.

## How do access rights and record rules limit the agent?

Odoo checks every API call against the permissions of the key's owner. Access rights decide whether that user may read, create, update or delete a model at all; record rules narrow this down to specific records; field groups hide individual fields. An agent should therefore run as its own bot user with exactly the permissions it needs.

### Access rights: which models and operations

Access rights (`ir.model.access`) grant create, read, write and delete per model and per group. The [Odoo security reference](https://www.odoo.com/documentation/19.0/developer/reference/backend/security.html) stresses that they are additive: a user gets the union of the rights from all their groups, and with no matching right the operation is refused.

For an agent, that means creating a dedicated group such as "AI agent – sales" and giving the bot user only that group. Every extra standard group widens its reach, because rights add up. According to the [access rights documentation](https://www.odoo.com/documentation/19.0/applications/general/users/access_rights.html), managing groups and technical permissions requires developer mode.

### Record rules: which records

Record rules (`ir.rule`) are domain conditions evaluated record by record once access rights allow the operation. The security reference distinguishes two kinds with very different behaviour:

- **Global rules** (no group) intersect. If two apply, both must match, so each new global rule restricts access further.
- **Group rules** unify. If two apply, either is enough, so they can widen access, but never beyond the limits set by global rules.

For example, a group rule with the domain `[("team_id", "=", 3)]` on `sale.order` confines the agent to one sales team's orders. Keep in mind that record rules are default-allow: if no rule applies, the access right alone decides.

### Field access and public methods

Fields can carry a `groups` attribute. Users outside those groups do not see the field in `fields_get()`, and an explicit read or write raises an access error.

The same reference contains a warning that matters a lot for agents: any public method, meaning any method whose name does not start with `_`, can be called over RPC with arbitrary arguments. A generic "execute any method" tool hands the model everything the bot user is allowed to do. Allow-list specific model and method pairs instead.

### A dedicated bot user

The JSON-2 reference explicitly recommends dedicated bot users for automated integrations. They get only the minimum permissions, their password can be left empty so that login and password authentication is disabled, and Odoo's change tracking shows the bot rather than a person. That last point pays off in practice: every record tells you whether a human or the agent touched it.

## What about transactions and API keys?

Each JSON-2 call runs in its own SQL transaction, and the documentation is clear that several calls cannot be chained into one. API keys have a maximum lifetime of three months and must be rotated. Both facts shape how you cut your agent's tools.

### One tool, one transaction

Agents like to work step by step: create the order, add lines, confirm it. If step three fails, you are left with a half-built order. Odoo's advice is to call a single method that performs all related operations in one transaction. `search_read` is the simplest example; `action_confirm` is a business one. Where no such method exists, the documentation suggests adding one in a dedicated module.

That is a sound rule for agent design generally: a business-level tool such as "create a draft quotation with lines" should be one server-side method in a small Odoo module, not a five-call sequence the model has to get right every time.

### Managing API keys

Keys are created under Preferences, Account Security. A description and a duration are mandatory, keys cannot last longer than three months, and the value is shown only once. Odoo 19 also lets you generate (`res.users.apikeys.generate`) and revoke (`res.users.apikeys.revoke`) keys through the API, so rotation can be automated. The documentation recommends one key per service, which lets you cut off a single integration without touching the others.

## Where does MCP fit in?

The Model Context Protocol (MCP) is an open standard that lets an AI client call tools hosted by a server. An Odoo MCP server translates tools such as "search records" into External API calls. It sits in front of the API rather than replacing it, so the bot user's permissions still apply to every request.

As of November 2026 we have not found an MCP server published by Odoo itself. Community projects exist, for example [twtrubiks/odoo19-mcp-server](https://github.com/twtrubiks/odoo19-mcp-server), licensed under Apache-2.0 and built on the JSON-2 API. It offers read tools such as `search_records` and `read_records`, write tools such as `create_record`, a read-only mode that disables writes, and an optional per-client API key so that Odoo permissions and audit logs apply to each user.

There are two sensible routes:

- **A generic MCP server:** quick to set up and useful for exploration and reporting in read-only mode. The downside is broad tools like "execute method", with the risk described above.
- **Your own business-level MCP server:** a handful of clearly named tools with fixed field lists, such as `create_draft_quote` or `get_delivery_status`. More work up front, but the model can only do what you designed for.

How MCP servers are structured and when they beat plain API tools is covered in our guide to [MCP servers for connecting AI agents](https://www.ruebstudio.de/en/guides/ai-agent-integrations/mcp-servers-connect-ai-agents).

## How do Community, Enterprise and Odoo Online differ?

The External API is part of Odoo's core, so it exists in both Community and Enterprise. The differences come from hosting and subscription: on Odoo's own plans, the documentation states that API access is only part of the Custom plan. Which models you can reach also depends on the apps installed.

- **Community** is licensed under LGPLv3 according to the [licence file in the Odoo repository](https://github.com/odoo/odoo/blob/19.0/LICENSE) and is usually self-hosted. You control the server, modules and logs, so you can install server-side methods written for your agent.
- **Enterprise** is built on top of Community and adds licensed apps. For an agent, that mainly means more models to work with; the integration mechanics are identical.
- **Subscription plans:** the [Odoo pricing page](https://www.odoo.com/pricing-plan) lists "External API" as part of the Custom plan, alongside Odoo.sh and on-premise hosting. The JSON-2 reference states that API access is not available on One App Free or Standard. Check your plan before you start building.
- **Odoo Online:** confirm early whether you can install custom Python modules in your setup. If you cannot, bundling multi-step writes into one server-side method becomes harder and you rely more on existing `action_` methods. The earlier removal date for XML-RPC and JSON-RPC also applies here.

Compared with large ERP suites, Odoo is a small integration surface: one API, one permission model, one data model. With SAP S/4HANA, by contrast, you choose between OData services, BAPIs and integration platforms, as our guide on [connecting an AI agent to SAP S/4HANA](https://www.ruebstudio.de/en/guides/ai-agent-integrations/connect-ai-agent-sap-s4hana) shows.

## What is a sensible step-by-step approach?

Start with one read-only use case, one bot user with a tightly scoped group and a few tools with fixed field lists. Add write access only once reading works reliably, and even then only as drafts that a person confirms.

1. **Check version and plan.** Odoo 19 or older? Does your plan include the External API? That determines JSON-2 versus RPC and whether you can deploy custom modules.
2. **Pick one process.** Delivery status or quotation drafting, with a clear definition of done.
3. **Identify models and fields** on your database's `/doc` page, including custom fields.
4. **Create the bot user and group.** Minimal access rights, record rules for the allowed records, empty password, its own short-lived API key.
5. **Build the tools.** Few, business-named functions; multi-step writes as one server-side method.
6. **Test on a copy.** Odoo can duplicate databases, so test against real data structures rather than production.
7. **Add an approval step.** The agent creates drafts, a person confirms. Consider direct confirmation only after weeks of clean runs.
8. **Rotate and monitor.** Automate key rotation, log every call and watch error rates.

## What are the limits and risks?

The biggest risks are over-broad permissions, chained calls without a shared transaction and tools that open arbitrary methods to the model. On top of that, the model will make wrong assumptions about fields and states, which your tool code has to catch.

- **Admin keys:** an agent holding an administrator's API key can do everything the administrator can. This is the most common and most damaging mistake.
- **Half-finished operations:** separate calls can be interleaved with other transactions. The documentation names reservations and payments as particularly risky.
- **Multiple global record rules:** the security reference warns that non-overlapping global rules can cancel each other out and remove all access. Test rules as the bot user, not as admin.
- **Invented fields:** the model knows Odoo from training data, not your database. Fixed field lists and parameter validation stop calls with fields that do not exist.
- **Expiring interfaces:** a new RPC integration on Odoo 19 is built on an API with an announced end date.
- **Personal data:** contacts, employee records and invoices contain personal data. Which data reaches which model is a decision for your data protection lead; an integration can be operated in line with the GDPR if permissions, field lists and model choice are designed for it. This is not legal advice.

If the data must not leave your infrastructure, the model can run locally; the tools and permission model stay the same and only the model provider changes. See [sovereign AI](https://www.ruebstudio.de/en/sovereign-ai) for that route.

## How do you get started?

The quickest worthwhile start is one read tool for a real process, such as delivery status from sales orders and deliveries, running as a dedicated bot user against a test copy of your database. That quickly shows whether data quality, permissions and answer quality hold up.

Answer three questions first: is the External API included in your Odoo plan, are you on Odoo 19 so you can start with JSON-2, and is someone allowed to maintain groups and record rules in developer mode? Once those are settled, the technical work is manageable.

If your data also lives outside Odoo, in a separate database or data warehouse, the guide on [connecting an AI agent to a database](https://www.ruebstudio.de/en/guides/ai-agent-integrations/connect-ai-agent-to-database) covers direct read access via SQL. For ready-made agents for quoting, service and sales that sit on top of an integration like this, see our overview of [AI agents for business processes](https://www.ruebstudio.de/en/ai-agents).

## Frequently asked questions

### Do I need Odoo Enterprise to connect an AI agent?

No. The External API is part of the core that Odoo Community also ships under LGPLv3. On Odoo's own subscription plans, however, the documentation states that API access is only included in the Custom plan, not in One App Free or Standard.

### Should a new integration still use XML-RPC?

Not on Odoo 19 or later. Odoo has deprecated /xmlrpc, /xmlrpc/2 and /jsonrpc and announced their removal for Odoo 22 (autumn 2028) and Odoo Online 21.1 (winter 2027).

### Is there an official Odoo MCP server?

As of November 2026 we have not found an MCP server published by Odoo itself. Several community projects build on the JSON-2 API; review them like any third-party code before production use.

### How long does an Odoo API key last?

You choose a lifetime when you create the key, and keys longer than three months cannot be created. Long-running integrations therefore need to rotate their key at least once a quarter.

## Sources

- [Odoo 19 Developer Reference: External JSON-2 API](https://www.odoo.com/documentation/19.0/developer/reference/external_api.html)
- [Odoo 19 Developer Reference: External RPC API (deprecated)](https://www.odoo.com/documentation/19.0/developer/reference/external_rpc_api.html)
- [Odoo 19 Developer Reference: Security in Odoo](https://www.odoo.com/documentation/19.0/developer/reference/backend/security.html)
- [Odoo 19 documentation: Access rights](https://www.odoo.com/documentation/19.0/applications/general/users/access_rights.html)
- [Odoo Pricing](https://www.odoo.com/pricing-plan)
- [Odoo Editions: Community vs. Enterprise](https://www.odoo.com/page/editions)
- [Odoo 19.0 LICENSE (LGPLv3)](https://github.com/odoo/odoo/blob/19.0/LICENSE)
- [twtrubiks/odoo19-mcp-server (community project)](https://github.com/twtrubiks/odoo19-mcp-server)
