Odoo

​

Video tutorial

​

Who is this for?

​

Prerequisites

• An Odoo 18 instance (Odoo Online, Odoo.sh or on-premise) whose plan gives access to the external API. On Odoo Online, the external API requires the Custom pricing plan.
• A dedicated service account in Odoo (an internal user), with read rights only on the data agents may use. The connector applies the Odoo rights of this account as-is.
• An API key for that account: log in as the service account, open Preferences → Account Security → New API Key, choose a duration and copy the key (Odoo shows it once). Note its expiry date: the configuration app warns 30 days before it.
• The database name. On Odoo.sh it differs from the sub-domain and is shown on the branch page; on-premise, it is the database selected at login.

context_id,agent_id,user_id

context_id,agent_id,user_id

You can read Odoo through the Odoo MCP server. It is read-only: you cannot create, modify or delete anything.
- Never guess a model or a field name. Use odoo_list_models to find the model, then odoo_describe_model to get its exact field names.
- When the user names a customer, a product or a lot, turn the name into ids with odoo_resolve before filtering on it.
- For totals, averages or evolutions, use odoo_aggregate (Odoo computes them). Do not read records to add them up yourself.
- Use odoo_count when the volume is unknown, then odoo_search_read with only the fields you need, paging with offset.
- If a model is refused, say it is not in the connector allowlist; do not try another model to work around it.

{
  "name": "odoo_search_read",
  "arguments": {
    "model": "sale.order",
    "domain": [["state", "=", "sale"], ["date_order", ">=", "2026-01-01"]],
    "fields": ["name", "partner_id", "date_order", "amount_total"],
    "order": "date_order desc",
    "limit": 20
  }
}

{
  "name": "odoo_aggregate",
  "arguments": {
    "model": "sale.order",
    "domain": [["state", "=", "sale"]],
    "measures": ["amount_untaxed:sum"],
    "groupby": ["date_order:year"],
    "orderby": "date_order:year asc"
  }
}

{
  "name": "odoo_resolve",
  "arguments": {
    "model": "res.partner",
    "text": "Azure Interior",
    "domain": [["customer_rank", ">", 0]],
    "limit": 5
  }
}

{
  "name": "odoo_describe_model",
  "arguments": {
    "model": "sale.order",
    "query": "partner"
  }
}

- Odoo.count:
    model: sale.order
    domain:
      - ['state', '=', 'sale']
      - ['date_order', '>=', '2026-01-01']
    output: confirmed

- Odoo.searchRead:
    model: sale.order
    domain:
      - ['state', '=', 'sale']
    fields:
      - name
      - partner_id
      - date_order
      - amount_total
    order: date_order desc
    limit: 20
    output: orders

- Odoo.aggregate:
    model: sale.order
    domain:
      - ['state', '=', 'sale']
    measures:
      - amount_untaxed:sum
    groupby:
      - date_order:year
    orderby: date_order:year asc
    output: revenue

- Odoo.resolve:
    model: res.partner
    text: '{{customerName}}'
    limit: 1
    output: matches
- conditions:
    '{{matches.error}} or !{{matches[0].id}}':
      - emit:
          event: odoo.customer.notFound
          payload:
            customerName: '{{customerName}}'
    default:
      - Odoo.searchRead:
          model: account.move
          domain:
            - ['partner_id', '=', '{{matches[0].id}}']
            - ['move_type', '=', 'out_invoice']
            - ['payment_state', '!=', 'paid']
          fields:
            - name
            - invoice_date_due
            - amount_residual
          output: invoices

​

Error Handling

​

Common Issues

• “This agent is not authorized to use the Odoo connector”: The calling agent is not in the allowlist. Open the configuration app → Agents → tick this agent under Authorized agents (or enable Allow all agents).
• “The calling agent could not be identified”: The MCP capability Scope does not declare agent_id, so Agent Creator never injects the agent identity. Set the Scope to context_id,agent_id,user_id on the capability (the Install capability button does it), then allow the agent in the configuration app.
• “Odoo refused the connection”: Run Test connection in the configuration app. Check the database name first (on Odoo.sh it is not the sub-domain), then the login, then the key. An Odoo API key cannot be read back: if it expired or was lost, generate a new one from the service account’s Preferences → Account Security and paste it.
• “The Odoo service account is not allowed to read this data”: the model is in the allowlist, but Odoo’s own rights refuse it. Grant the service account the matching read access in Odoo (user groups, record rules), or remove the model from Readable models.
• odoo_list_models returns allowlist patterns instead of models: Odoo restricts the model registry (ir.model) to administrators, and a read-only service account usually cannot list it. The connector then answers from the allowlist itself, so a pattern such as stock.* appears as is; the agent can still call odoo_describe_model on a concrete model such as stock.lot.
• Service-specific gotcha: relational fields (partner_id, product_id…) return the display name of the related record even when the related model is not in the allowlist. This is standard Odoo behaviour: the connector never reads the related record itself, but if a display name is sensitive, restrict the field through the service account’s Odoo rights.

​

External Resources