Zenithonsoft

Connecting External AI Agents to Odoo 20 via MCP: A Practical Guide for Claude, Cursor & Copilot

In earlier Odoo versions, connecting an external AI tool—such as Claude Desktop, Cursor IDE, or an autonomous workflow runner—required tedious middleware. Developers had to write brittle XML-RPC scripts, stand up custom REST API modules, or maintain fragile webhook relays that frequently broke during version upgrades.

With Odoo 20, that friction disappears. Odoo 20 natively introduces a Model Context Protocol (MCP) Server (ai_mcp).

Instead of custom API wrappers, Odoo 20 exposes a standardized /mcp interface. Any MCP-compatible AI client can discover database models, inspect schemas, and execute authorized server actions securely.

Here is an architectural walkthrough of how Odoo 20’s MCP server works, how to configure external clients, and how to deploy agentic workflows safely.

What is Model Context Protocol (MCP)?

Originally open-sourced by Anthropic and rapidly adopted by tools like Cursor, Claude Desktop, and GitHub Copilot, Model Context Protocol (MCP) acts as a universal communication layer between LLMs and external enterprise data systems.

Traditional Integration (Odoo 16/17/18)
[ External AI Client ] ──▶ [ Custom Python Middleware ] ──(XML-RPC)──▶ [ Odoo Database ]
                           (Requires custom maintenance & re-authentication)

Odoo 20 Native MCP Architecture
[ External AI Client ] ────────────────────(MCP / OAuth2)────────────▶ [ Odoo 20 /mcp ]
(Claude, Cursor, Copilot)                                                 ├── Model Discovery
                                                                          ├── Schema Introspection
                                                                          └── Safe Tool Execution

In MCP, external clients do not need hardcoded API endpoints for each business object. Instead, the protocol defines standard primitives:

  1. Resources: Read-only enterprise data (e.g. customer records, product catalogs, invoice PDFs).
  2. Prompts: Reusable operational templates stored directly inside Odoo.
  3. Tools: Executable functions (e.g. creating a lead, confirming a sales order, checking inventory on hand).

1. How the Odoo 20 MCP Server Operates

The native Odoo 20 MCP engine lives in the ai_mcp module. It exposes an authenticated JSON-RPC/SSE endpoint at:

https://your-odoo-domain.com/mcp

Security & Authentication

Unlike legacy integrations that relied on user passwords or static API keys, Odoo 20 MCP uses OAuth2 Bearer Tokens:

  • You provision an API Client in Odoo’s General Settings under Technical > OAuth & MCP Clients.
  • Each token is scoped to specific model domains (e.g. res.partner:read, sale.order:read, crm.lead:write).
  • All actions executed via MCP run strictly under the permissions of the assigned service user. If the user cannot delete records in Odoo’s UI, the AI agent cannot delete them over MCP.

2. Dynamic Tool & Schema Discovery

When an MCP client connects to Odoo 20, it initiates a handshake using tools/list.

Odoo dynamically reflects its authorized ORM models as callable tools:

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "params": {}
}

Odoo responds with JSON schemas describing each available operation, including required fields, parameter types, and model constraints:

{
  "tools": [
    {
      "name": "odoo_search_read",
      "description": "Search and read records from any accessible Odoo model.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "model": { "type": "string", "description": "Technical model name (e.g. crm.lead, sale.order)" },
          "domain": { "type": "array", "description": "Odoo search domain filter" },
          "fields": { "type": "array", "items": { "type": "string" } },
          "limit": { "type": "integer", "default": 10 }
        },
        "required": ["model"]
      }
    },
    {
      "name": "odoo_create_record",
      "description": "Create a new record in an authorized Odoo model.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "model": { "type": "string" },
          "values": { "type": "object" }
        },
        "required": ["model", "values"]
      }
    }
  ]
}

Because schemas are generated dynamically, any custom fields added via Odoo Studio or custom addons are automatically exposed to the AI client without manual code adjustments.

3. Configuring Claude Desktop with Odoo 20

You can connect Claude Desktop to your Odoo 20 instance by configuring your local claude_desktop_config.json:

{
  "mcpServers": {
    "odoo-production": {
      "command": "npx",
      "args": [
        "-y",
        "@zenithonsoft/odoo-mcp-bridge",
        "--url",
        "https://erp.yourcompany.com",
        "--token",
        "YOUR_OAUTH2_BEARER_TOKEN"
      ]
    }
  }
}

Once connected, you can prompt Claude in natural language:

“Look up our top 5 overdue invoices in Dubai, cross-check the assigned sales reps in Odoo, and summarize the collection risk.”

Claude queries Odoo over MCP, filters account.move with the appropriate domain, and formats a response directly in the desktop interface—zero manual exports required.

4. Cursor IDE: Vibe Coding with Live Odoo Context

For developers building custom Odoo addons, connecting Cursor IDE via MCP is a game-changer:

  1. Live Schema Validation: Cursor can inspect actual database columns, relational Many2one links, and selection fields directly while you write Python code.
  2. View Architecture Inspection: Ask Cursor: “Find the XML arch definition for the project task form view in this Odoo instance and suggest where to inject our custom inspection widget.”
  3. Automated Test Scaffolding: Cursor inspects model constraints and generates complete TransactionCase test classes that match your production database structure.

🤖 Connecting External AI to Custom Odoo Addons?
Custom methods exposed via controllers or API endpoints must adhere to strict permission scoping to avoid accidental database pollution or unauthenticated execution loops. Get your custom endpoints checked by Zenithonsoft’s automated AST review:
👉 Request a Free 24h Odoo Code Review & Architecture Audit →

5. Enterprise Guardrails: Preventing Runaway AI Actions

Autonomous AI execution brings real business risks. Odoo 20 introduces built-in architectural guardrails:

A. Tool Call Limit Confirmation

In Odoo 20, if an agent enters a recursive loop or attempts an excessive number of consecutive tool calls, execution pauses immediately and prompts the user for manual confirmation before proceeding.

B. Dedicated Service Accounts

Never connect an external MCP agent using an Administrator account (base.group_system). Create a dedicated Service User with the minimum necessary operational groups (e.g. Sales / User, Inventory / User).

C. IAP Credit Consumption Monitoring

Odoo 20 AI features utilize In-App Purchase (IAP) credits. Set daily usage quotas in General Settings to ensure automated cron agents don’t generate unexpected monthly invoices.

Summary: The Future of Odoo Integration

The arrival of native MCP in Odoo 20 signals a fundamental shift in enterprise architecture. The era of writing repetitive point-to-point API scripts is coming to an end. By standardizing on Model Context Protocol, Odoo instances become natively agent-ready.

Optimize Your Odoo 20 Architecture with Zenithonsoft

Planning an upgrade to Odoo 20 or looking to implement secure AI agent workflows?