Skip to content

Connection and discovery

New in v1.6.0

odoo_version names the odoo-tools copy that answers (plugin block), also when the policy is locked. An answer without policy comes from a copy older than 1.5.0, and /odoo-doctor stops there; in Claude Code it also runs the copies check. See Identify the environment. When the Odoo tools are not loaded, /odoo-doctor recognizes the app's not_started status as the Cowork and Claude chat case, tells a cloud session apart and, when python3 is missing, gives the fix for your system. See Health check.

New in v1.5.1

/odoo-doctor first checks whether the Odoo tools are loaded where it runs, gives Odoo-side advice only once Odoo refused the connection, and always ends with a support report with no keys, URLs, logins or record data. See Health check.

New in v1.5.0

odoo_version also returns a policy block with the permission policy in force, and /odoo-doctor reports it. odoo_list_models leaves out the models the policy allows nothing on, and odoo_access_check adds the policy's answer next to Odoo's own. See Permission policy.

Before operating against a new instance, identify its version, edition and deployment. The compatibility layer uses these details to resolve model and field names, so you almost never need to branch your queries by version.

1. Identify the environment

Call odoo_version. It returns:

  • version: major integer (10-19)
  • raw_version: the full version string reported by Odoo
  • edition: community | enterprise | unknown
  • deployment: onprem | saas
  • transport: the active transport: json2 on Odoo saas~18.4 / 19.0+ with an API key; jsonrpc(auto), or jsonrpc / xmlrpc after a fallback, otherwise
  • transport_notice: null, or why the deprecated /xmlrpc or /jsonrpc endpoints are in use on Odoo 19+ and how to move to JSON-2 (for example, create an API key and put it in the plugin options)
  • policy (since v1.5.0): the profile (profile), the policy file (file), the digest, whether Read-only mode is on (readonly), the hidden tools (hidden_tools), the openings of sensitive models with their reason and expiry (opened_sensitive), the released fields (released_fields), the warnings (warnings) and, when the policy could not be loaded, error and error_code. See What the tools report.
  • plugin (since v1.6.0): the odoo-tools version that answered (version) and, in Claude Code, its installed copy (copy, plugin@marketplace, for example odoo-tools@transgenia-odoo-tools), read from the name of the data folder that Claude Code gives each copy. With two copies installed, it tells which one runs.

Since v1.4.0, odoo_version signs in before answering: a wrong API key or password returns an authentication error instead of passing as a working connection.

When the Odoo user is an administrator (base.group_system), policy.warnings carries warning W10: Odoo's access rights narrow nothing, and the permission policy is the only narrowing layer. Prefer a dedicated user with the fewest groups that work. When the policy is locked, odoo_version answers with the plugin and policy blocks only and a note that names the option or the file to fix, without contacting Odoo.

An answer without a policy block (and without a note) comes from an odoo-tools copy older than 1.5.0, with no permission policy; it is often a second copy, installed from another place. The guided route and /odoo-doctor stop there, before any write. See Two copies of odoo-tools.

Claude Code only

If odoo_version is not among the tools, the MCP server is not running on this surface. On Cowork and Claude chat it never runs (see Where it works); on Claude Code, check the plugin options and Troubleshooting. /odoo-doctor starts with this check.

2. Health check with /odoo-doctor

The /odoo-doctor command runs a full diagnostic, writing nothing, in this order, and stops at the first step that explains the problem:

  1. Are the Odoo tools loaded? Before it runs anything, it looks at its tool list. If odoo_version is not there, the MCP server is not running in this session, so it runs no shell command and checks no Python before it knows where you use Claude (in Cowork, commands run in a virtual machine, not on your computer) and gives no Odoo-side advice (plan, API key, transport, database). It reads the odoo-tools session diagnostics: line that the session-start hook writes from your computer (Cowork runs the plugin's hooks on your computer, outside the virtual machine; Claude chat runs none) and, if it does not know, asks you where you use Claude. If the app shows the plugin's server with the status not_started and the reason user_config_unsupported, it knows you are in Cowork or Claude chat. In Cowork or Claude chat it tells you that the Odoo tools do not run there, by design of those apps, and that nothing is wrong with your account, your Odoo or your Python; that status is expected, not a bug, and no update changes it. It offers a local session of the Code tab of Claude Desktop or Claude Code, where the plugin is synced to the same account, and assisted setup by Transgenia. In a cloud session (of the Code tab, or Claude Code on the web), the plugin can be synced but its options stay on the computer where you entered them, so the server does not start: it does not ask you for the options there and offers you the same. In Claude Code on your computer, the server did not start. The usual causes are an empty URL, database or login, a second copy of the plugin or no python3 command (on Windows, claude mcp list then reports the server as Failed to connect with Connection closed, without naming Python; on macOS, python3 comes with Apple's Command Line Tools). It runs the copies check and, for the copy it keeps, the options check: they read what Claude Code prints, contact nothing and never show the key (see Two copies of odoo-tools). If python3 is not found or prints no version, that is the cause: it gives you the fix for your system and stops. Otherwise it shows you both outputs as they are and sends you to Step 0b of the guided route. The commands the copies check prints are for a terminal (PowerShell or Terminal), not for /plugin.
  2. Calls odoo_version. First it reads its plugin block: the odoo-tools version that answered and its copy (plugin@marketplace). If the answer has no policy, a copy older than 1.5.0 answered, without the permission policy: it tells you, runs the copies check and stops there. Otherwise it reports version / edition / deployment / transport and, when it is not null, the transport_notice with its fix. It also reports the policy block: the profile, whether a policy file is set, the digest, the hidden tools, the openings with their reason and expiry, and every warning; it shows W10 prominently and recommends a dedicated least-privilege user. When error is set, the policy is locked: it tells you that every other Odoo tool is disabled until you fix the file or the Permission profile / Permission policy file options and reconnect (/mcp), and it stops there. Then it runs the copies check once and adds its result to the table: two copies can be active while the connection works, and then the options dialog and the tools may belong to different copies.
  3. Calls odoo_connections and lists the active sessions.
  4. Does a scoped test read: odoo_search_read { "model": "res.partner", "fields": ["name"], "limit": 1 }. Then it calls odoo_online_profile (read-only) and adds to the table the series (e.g. saas~19.2 on Odoo Online), how sure the deployment detection is (deployment_confidence) and any hint, such as an API key that expires soon. If the deployment is saas, the Odoo Online limits too. Only then, if Odoo refused the connection, do the Odoo-side checks apply: on Odoo Online, external API access needs a Custom plan; an expired or revoked API key; the database name.
  5. If any step fails, it shows the exact error and points you to /odoo-tools:odoo-setup-mcp (or odoo-setup-cli). It always ends with a support report you can send to Transgenia, with no keys, URLs, logins or record data: in Claude Code it runs --diagnose on the plugin's local folders; in Cowork it writes it from step 1, and in Claude chat it names the surface only. See Support.

3. Explore the schema

Every instance differs. Before querying fields you do not know:

  • odoo_list_models: lists the installed models, optionally filtering by a name fragment (like). Since v1.5.0 it leaves out the models the permission policy allows nothing on, and says how many (hidden_by_policy).
  • odoo_fields_get: returns the field definitions of a model (cached). It accepts historical or modern names; the compatibility layer resolves to the correct one.
  • odoo_module_info: installation status and metadata of a module by its technical name (useful to know whether an Enterprise module is present).
  • odoo_access_check: whether the signed-in user may read, write, create and delete on a model (record by record with ids on Odoo 18+), and whether the user may export. Useful when a call is refused for permissions. Since v1.5.0 it also returns policy (what the permission policy allows) and a note when Odoo allows something the policy refuses.
  • odoo_api_catalog: a model's methods with their parameter names in order, for JSON-2 and odoo_execute.

All of them are described in the Tools reference.

Example: discover the contact fields

odoo_fields_get {
  "model": "res.partner",
  "attributes": ["string", "type", "required"]
}

4. Choose the right surface

  • If you use Claude Code and python3 3.9+ is available → MCP server (all the tools + compatibility; no third-party dependencies).
  • If you use Claude Code without Python but with Docker → the MCP server as a container (/odoo-tools:deploy-local, see Local deployment).
  • If you only have Node → fallback CLI (see Fallback CLI).

Continue with the Tools reference.