Architecture Overview
Module structure, file tree, Odoo models, HTTP routes, and system component diagram
Architecture Overview
odoo_ai_mcp_server is a top-level Odoo 19 application (application: True) that implements an MCP server inside the Odoo HTTP framework. It exposes a single JSON-RPC endpoint at POST /mcp and a full OAuth 2.1 authorization server at /oauth/*.
System Component Diagram
Rendering diagram…
Module File Tree
odoo_ai_mcp_server/
├── __init__.py imports controllers, models, wizard
├── __manifest__.py module metadata, data file list, assets
├── ARCHITECTURE.md developer reference (this doc's source)
│
├── controllers/
│ ├── __init__.py imports utils, oauth, discovery, mcp
│ ├── mcp.py POST /mcp — all 16 MCP tools, JSON-RPC
│ ├── oauth.py /oauth/authorize · /oauth/token · /oauth/register
│ ├── discovery.py /.well-known/oauth-* metadata routes
│ └── utils.py gateway flag, model validation, access policy
│
├── models/
│ ├── __init__.py
│ ├── odoo_ai_mcp_enabled_models.py ai_connector.model_policy (CRUD allowlist)
│ ├── odoo_ai_mcp_log.py ai_connector.audit_log + purge cron
│ ├── odoo_ai_mcp_key.py odoo_ai_mcp.api.key (API key records)
│ ├── odoo_ai_mcp_oauth.py OAuth clients, codes, tokens, service
│ ├── odoo_ai_mcp_rate_limit.py ai_connector.rate_limit
│ ├── odoo_ai_mcp_approval.py ai_connector.approval (delete queue)
│ ├── odoo_ai_mcp_dashboard.py Spreadsheet dashboard integration
│ ├── odoo_ai_mcp_client_config.py Connect Wizard config record
│ └── res_config_settings.py Settings → ir.config_parameter bridge
│
├── security/
│ ├── ir.model.access.csv CRUD grants per group
│ └── security.xml groups + record rules
│
├── views/
│ ├── oauth_templates.xml QWeb: consent + error pages
│ ├── odoo_ai_mcp_connect_views.xml Connect app views
│ ├── odoo_ai_mcp_enabled_models_views.xml
│ ├── odoo_ai_mcp_log_views.xml
│ ├── odoo_ai_mcp_backend_views.xml Dashboard
│ ├── odoo_ai_mcp_menu.xml Menu structure
│ └── res_config_settings_views.xml Settings block
│
├── wizard/
│ ├── __init__.py
│ ├── odoo_ai_mcp_model_selection_wizard.py
│ └── odoo_ai_mcp_model_selection_wizard_views.xml
│
└── static/
└── src/
├── scss/ MCP UI styles (light + dark)
├── fields/mcp_platform_picker/ Platform picker widget
├── systray/mcp_approval_systray Approval badge in systray
└── xml/chatter_patch.xml Chatter extensionHTTP Routes
| Route | Methods | Auth | Description |
|---|---|---|---|
POST /mcp | POST | public | Main MCP JSON-RPC endpoint. Bearer or session auth. |
/oauth/register, /register | POST | public | Dynamic client registration (RFC 7591-style). |
/oauth/authorize | GET, POST | public | GET: consent page. POST: issue auth code + redirect. |
/oauth/token | POST | public | Token exchange (authorization_code, refresh_token). |
/.well-known/oauth-protected-resource | GET | public | Protected resource metadata or 404. |
/.well-known/oauth-protected-resource/mcp | GET | public | Same, MCP-scoped path. |
/.well-known/oauth-authorization-server | GET | public | AS metadata or 404. |
/.well-known/openid-configuration | GET | public | OIDC-style metadata or 404. |
All routes have CSRF disabled (csrf=False) since they are consumed by non-browser clients.
Naming Conventions
| Pattern | What It Refers To |
|---|---|
ai_connector.* | Core gateway data models — policy, audit log, rate limit, approval, wizard |
odoo_ai_mcp.* | OAuth-specific models — clients, codes, tokens, service, API keys |
ai_integration.* | ir.config_parameter namespace for all MCP settings |
AIIntegration*Controller | HTTP controller classes |
group_ai_integration_* | Security group XML IDs |
odoo_* (tool names) | MCP-facing tool names; map to ORM via method_map in mcp.py |
Odoo Models Reference
| Model | Table | Purpose |
|---|---|---|
ai_connector.model_policy | ai_connector_model_policy | Per-model CRUD allowlist |
ai_connector.audit_log | ai_connector_audit_log | Immutable audit trail |
ai_connector.rate_limit | ai_connector_rate_limit | Per-minute request counters |
odoo_ai_mcp.oauth.client | odoo_ai_mcp_oauth_client | Registered OAuth clients |
odoo_ai_mcp.oauth.code | odoo_ai_mcp_oauth_code | Authorization codes (10 min TTL) |
odoo_ai_mcp.oauth.token | odoo_ai_mcp_oauth_token | Access + refresh tokens |
odoo_ai_mcp.oauth | (AbstractModel) | OAuth service API |
ai_connector.policy_wizard | (TransientModel) | Batch model configuration wizard |
See Request Flows for end-to-end flow diagrams.