Frequently Asked Questions

Installation & Compatibility

Which Odoo versions are supported?

Odoo 19.0 (Community and Enterprise). The module technical name is odoo_ai_mcp_server.

Are any external Python packages required?

No. The module uses only Odoo core libraries (standard library + ORM). No pip installs needed.

Does it work without HTTPS?

The module works over HTTP for local development, but HTTPS is required for OAuth 2.1 web clients (Claude.ai, ChatGPT.com). Desktop clients using API keys can work over HTTP in dev environments.

Authentication & Clients

Which clients use OAuth vs API keys?

• OAuth 2.1 — Claude.ai, ChatGPT.com (web-based AI assistants)
• API Key — Cursor, Claude Desktop, VS Code, and all other desktop/IDE clients

How do I connect Claude.ai?

1. Enable OAuth in Settings → MCP Server.
2. Open MCP Server → Connect, select Claude.ai, and copy the MCP URL.
3. In Claude.ai, add a new custom MCP connector with that URL.
4. Authorize with your Odoo login in the browser consent page.

How do I connect Cursor?

1. Open MCP Server → Connect, select Cursor.
2. Copy the generated JSON configuration.
3. Paste it into .cursor/mcp.json in your project root (or global Cursor settings).

Can multiple users connect simultaneously?

Yes. Each user creates their own credential via the Connect Wizard. All connections are independent and run as their respective Odoo users.

Are API keys stored in plaintext?

No. API keys are stored as SHA-256 hashes. The raw key is shown once in the Connect Wizard — store it immediately. If lost, delete the credential and regenerate.

Security

Does the AI have more access than the Odoo user?

Never. The AI always runs as the authorizing Odoo user using their full Odoo groups, ACLs, and record rules. Model Access Rules are an additional restriction — they can only reduce what the user can access, never expand it.

What prevents the AI from deleting important data?

All delete operations (odoo_unlink) are always routed through the approval queue. The AI cannot permanently delete anything without a human reviewer explicitly approving the request in Odoo.

Can the AI install or remove Odoo modules?

Module operations are queued for human approval and cannot be executed by the AI directly. The core modules base, web, mail, and odoo_ai_mcp_server are additionally protected and cannot be queued for uninstall.

What is the difference between MCP Model Access Rules and Odoo ACL?

Odoo ACL controls what a user can do at the ORM level. MCP Model Access Rules are an additional MCP-specific allowlist that controls which models are exposed to AI clients. Both must be satisfied for a tool call to succeed.

Tools & Usage

How do I expose a model to MCP tools?

1. Go to MCP Server → Model Access Rules.
2. Create a new rule for the model.
3. Enable the CRUD flags you want (Can Read, Can Create, etc.).
4. Save.

Why is a tool call returning permission denied?

Check:

1. Is the MCP gateway active? (Settings → MCP Server → Active AI Assistant Gateway)
2. Is there an active Model Access Rule for the model?
3. Does the rule have the correct can_* flag enabled (e.g. can_write for odoo_write)?
4. Does the Odoo user have native ORM access to the model?

Can I limit which fields are readable?

Not directly via MCP Model Access Rules — field-level restrictions use Odoo’s native field security (groups attribute on fields). MCP respects those automatically.

Why does odoo_unlink return an approval request instead of deleting?

This is by design. All delete operations require human review. See Delete Approvals.

Performance & Operations

How do I disable rate limiting?

In Settings → MCP Server, toggle Enable MCP Rate Limiting off.

The gateway is toggled off but AI clients can still connect for a few minutes. Why?

The gateway flag is cached for 5 minutes by is_gateway_active() in the controller. This is a known limitation — wait up to 5 minutes or restart the Odoo service to force an immediate effect.

How do I purge audit logs?

Logs are purged automatically by a daily cron based on the MCP Log Retention setting (default: 30 days). For a manual purge from the Odoo shell:

env['ai_connector.audit_log'].purge_expired_history()

Rate limit rows are accumulating in the database. How do I clean them?

Run from the Odoo shell:

env['ai_connector.rate_limit'].cleanup_old_windows(hours=2)

Note: there is no scheduled action for this in the current version — it must be run manually.

Troubleshooting

The /mcp endpoint returns HTTP 503

The gateway is inactive. Go to Settings → General Settings → MCP Server and enable Active AI Assistant Gateway.

The /mcp endpoint returns HTTP 401

Authentication failed. Verify:

• The Bearer token is correct and not expired.
• The user is not the public user.
• For OAuth: the access token has not expired (default 1 hour TTL).

OAuth consent page shows an error

Check:

• ai_integration.oauth_enabled is True.
• ai_integration.oauth_advertise_discovery is True.
• The redirect_uri in the authorization request matches the registered client’s redirect_uris.
• The resource parameter matches https://your-odoo.com/mcp.