How Odoo 20's MCP server works, checked against the code

At Odoo Experience 2026, Ahmed and Abdurrahman from Odoo’s AI team presented the MCP server that lets outside AI clients such as Claude, ChatGPT, Grok or n8n work on an Odoo database through the Model Context Protocol. The talk is for admins who want to connect these clients and developers who write tools for them. It explains the design choices and shows a tool being built and tested live.

What the talk covers

Why MCP if Odoo already speaks JSON-RPC

MCP is itself an RPC protocol, the speakers say (8:52). What it adds is three things:

• A shared standard. Every client and server that speaks MCP can talk to each other, instead of one integration per pair of systems (5:25).
• Discovery at runtime. An agent loads only short tool descriptions, then fetches a tool’s details when it needs it. It doesn’t have to read the API documentation into its context first (10:48).
• Reach. ChatGPT, Claude, n8n and editors like VS Code already include MCP clients (12:12).

Four design decisions

Stateless, not stateful (14:03). A stateful MCP server keeps a Server-Sent Events stream open to push progress and “tool list changed” notifications. An Odoo worker handles one request at a time, and according to the speakers a typical Odoo Online server hosts 2,500 to 5,000 databases on four workers (15:48). Four open connections would block the whole server. Odoo’s tools run fast and the tool list rarely changes, so Odoo dropped notifications (17:57). In the code, /mcp accepts only POST, answers client notifications with an empty 202, and implements just initialize, ping, tools/list and tools/call. There are no resources or prompts. If the tool list changes, you refresh it in the client.

Two kinds of errors (18:50). An unknown method is a JSON-RPC protocol error (-32601). Clients rely on it to fall back to an older protocol version. Every other failure, such as a team that doesn’t exist or missing access rights, comes back as a tool result marked isError with the error text, so the model can correct itself or tell the user.

Which company (20:15). The module adds a tool, MCP Retrieve initial context, whose description tells the model to call it once at the start of every conversation. It returns the user, their time zone, their default company (treated as the active one) and the companies they may use, and it reminds the model that dates are in UTC. To work in another company, name it in your request.

Tools are server actions (21:55). The AI app’s tools are server actions marked Use in AI, with a tool name, description and JSON schema. That was already the case in 19.0. ai_mcp adds two switches to them, Available in MCP and Readonly Tool. Out of the box, four read tools are available over MCP: Get Models, Get Fields, Search and Read group, plus the initial-context tool. Create Records and Update Records exist but stay off until an admin enables them (22:42). The UI tools the built-in agent uses (opening menus, list or kanban views) are not exposed at all (23:50).

Writing your own tool

A tool has five parts (24:57): a name the model calls it by, a description, a JSON schema for its parameters, the code, and the Available in MCP toggle. In the demo the server action is named with an AI Tool: prefix, which Odoo’s own tools follow, and it is of type Execute Code (27:52). The code stores its answer in ai['result'].

The description is a prompt, read before anything else. The speakers suggest four parts: what the tool does, when to use it, what it returns, and when not to use it, which keeps the model from loading tools it doesn’t need (26:23).

The demo builds a “create Helpdesk ticket” tool and lets Claude test it through a small command-line MCP client made by the team (29:51). Claude suggests edge cases. A ticket for a “billing” team that doesn’t exist is accepted when it should be rejected, so the code gets a check and Claude confirms the fix (34:23). Odoo validates the arguments against the JSON schema before the code runs, but a value that is well-formed and still wrong, like that team name, is for your code to catch.

Connecting clients

• The address is your database URL plus /mcp, with OAuth 2 for authentication (38:16). On the consent screen you choose how long access lasts: 1 day, 1 month (the default) or 1 year. Administrators also get Never. The choice is capped by the API-key duration allowed for your groups (40:19). Each connection becomes an API key with the MCP scope. You can also create such a key yourself under Preferences → Security and give it to a client as a bearer token, which the module’s own description suggests. Only internal users can authorize a client.
• Dynamic Client Registration (DCR) is off by default because the endpoint can be spammed. Turn it on to let a new client register, then turn it off again (39:11). Both settings are under Settings → Integrations → MCP OAuth. Clients that use Client ID Metadata Documents (CIMD) are allowed by URL instead, and the default list covers ChatGPT, Claude, Claude Code and Grok, as the speakers say (39:41). Admins can also register a client by hand with its redirect URIs.
• n8n: an AI Agent node with an MCP Client tool, …/mcp, and MCP OAuth2 credentials. The demo answers customer emails about order status and passes the rest to a Helpdesk ticket for a person (36:21).
• Claude: Customize → Connectors → Add custom connector with the /mcp URL (42:14). ChatGPT: turn on developer mode in the security settings first, then add an MCP app the same way (43:50).

From the Q&A

• Permissions: the token belongs to the user who logged in, so the client can only do what that user can (51:12). The code bears this out: tool code runs as that user, not as superuser. The speakers also said an enabled tool is enabled for every user (49:07). That isn’t quite the case. A tool appears and runs only if the user may run its server action. Set Allowed Groups on the action to limit it to those groups. Without groups, the user needs write access to the tool’s model.
• Confirmation before a write is up to the client (Claude and ChatGPT have settings for it). The server runs whatever tool is called (53:06). In the code, MCP calls are marked as already confirmed, so a tool that asks for confirmation in Odoo’s own AI chat won’t ask over MCP.
• Versions: MCP first came in Odoo 19.4 (an Online-only release) without OAuth. OAuth, which ChatGPT and Claude need, came in 20 (52:25).

Checked in the code

Community: odoo/odoo at 20.0 (commit 3ff8b8d9, October 23, 2026). Enterprise: odoo/enterprise at 20.0 (October 23, 2026) and saas-19.4. Enterprise code is private, so we name the module rather than link to it.

Community, Enterprise and Online

The MCP server is Enterprise (Odoo Online, Odoo.sh or on-premise Enterprise with the AI app). A Community database has no /mcp endpoint. It can still reach outside tools through the plain external JSON-RPC API with an API key, which is what the speakers compare MCP with. Since 20.0, Community’s API-key form suggests “Odoo MCP” as a key name (df546e00).

What developers and admins should check

• Limit write tools with groups. Set Allowed Groups on Create Records, Update Records and your own write tools before you enable them for MCP. For an automation such as n8n, also connect it as a dedicated user whose access rights cover only what it needs.
• Mark read tools as Readonly Tool. Clients receive it as readOnlyHint / destructiveHint and can treat write tools more carefully.
• Write descriptions as prompts: what, when, returns, when not.
• Check values, not just types. The JSON schema is enforced, but your code must reject well-formed nonsense with a clear error. Test with a model, not just by hand.
• Keep DCR off. Add a client’s CIMD URL instead, or register it by hand.
• Confirmation is the client’s job. Turn on approval for write tools in Claude or ChatGPT if you want a human in the loop.
• Revoke access by deleting the client’s API key (scope MCP) in the user’s security settings.

Sources

• Odoo MCP: A technical deep-dive into AI connectors, Odoo, Odoo Experience 2026, and the event page
• Model Context Protocol specification
• odoo/odoo branch 20.0; odoo/enterprise branches 20.0 and saas-19.4 (private): modules ai, ai_mcp