Quick fixes for connection errors, permission problems, OAuth issues, and dashboard glitches – all in one place.
Overview
When something does not work with Odoo MCP Connection, the cause is usually one of these: wrong connection URL, expired or missing token, permissions too tight, MCP turned off, or a portal page not published.
This page lists the most common symptoms, what they mean, and exactly what to do. Use it before contacting IT – most fixes take less than five minutes.
How to Diagnose Any Problem
Follow this checklist every time something fails:
Is MCP enabled? Go to Odoo MCP Connection → Configuration → Settings and confirm Enable MCP Connection is turned on.
Test inside Odoo first. Open your API key → API Console tab → click Run API Test. If this fails, the problem is in Odoo – not your AI tool.
Check the audit log. Go to Audit Logs, find the failed entry, and read the error message.
Verify the URL. Copy the MCP Endpoint from the API Console. On servers with multiple databases, it must include ?db=your_database_name.
Review permissions. Confirm the key’s Odoo user, App Access, and Model Access allow the action AI tried to perform.
Step-by-Step Fixes by Problem
AI tool cannot connect at all
- Open Configuration → Settings – turn on Enable MCP Connection.
- Copy the full MCP Endpoint URL from the API key’s API Console (include
?db=). - Confirm the API key is Active and not past its Expires On date.
- If you rotated the token, paste the new token into your AI tool.
- Run Run API Test on the key – status must show Success.
Claude OAuth sign-in fails
- Confirm your Odoo site uses HTTPS (not http://).
- On the API key or OAuth client, add redirect URI:
https://claude.ai/api/mcp/auth_callback - Copy Client ID and Client Secret fresh from Odoo into Claude settings.
- Complete the browser sign-in without closing the window early.
- If it still fails, try Create OAuth Client again from a new API key.
AI says "access denied" or returns no data
- Check which Odoo User is linked to the API key – log in as that user in Odoo and try the same action manually.
- Open App Access tab – add the Odoo app that owns the data (Sales, Accounting, CRM, etc.).
- Open Model Access tab – add the data type and enable Allow Read.
- Check Field Allowlist and Domain Filter – they may be too restrictive.
- Re-run your question in AI and check Audit Logs for the exact error.
Portal dashboard blank, error, or not loading
- Confirm the page is Active and Published.
- Copy the Page URL from the portal page form (with
?db=). - If widgets show zero, set an API Key on the page whose user can read that data.
- If you see a server error, open the page in Odoo and fix the Page Specification – or copy from a working demo page like
demo-contacts. - Upgrade the Odoo MCP Connection module to the latest version if errors persist.
Problem & Solution Quick Reference
| Symptom | Most Likely Cause | Fix |
|---|---|---|
404 on /mcp |
Missing database name in URL |
Add |
401 Unauthorized |
Wrong, expired, or rotated token |
Rotate Token, copy new token, update AI tool |
503 Service Unavailable |
MCP Connection disabled |
Enable MCP Connection in Settings |
Claude OAuth 401 |
HTTP site or bad credentials |
Use HTTPS; verify Client ID, Secret, and redirect URI |
Access denied for model … |
Key lacks permission for that data |
Add App Access or Model Access on the key |
Empty search results |
Domain filter or user rights |
Relax Model Access rules; test as linked Odoo user |
Rate limit exceeded |
Too many requests too fast |
Wait and retry; raise limits in Settings or on the key |
Token not visible |
Hidden after save (by design) |
Click Rotate Token; copy immediately |
IP blocked |
IP allowlist / denylist |
Clear or update IP rules on the key |
Portal 500 error |
Invalid page specification |
Fix Page Specification JSON or use a demo page as template |
Portal widgets show 0 |
API key user cannot read data |
Assign an API key with correct read access to the page |
Bulk job failed |
Permission or bad data |
Read Error Message on Bulk Jobs form; fix Model Access |
Cannot install generated module |
Missing import app |
Install “Base Import Module” from Odoo Apps |
Max API keys reached |
Limit set in Settings |
Archive unused keys or raise Max Active API Keys |
Frequently Asked Questions
Do I need a separate API key for each AI tool?
Yes – recommended. Separate keys make audit logs clearer and let you revoke one tool without breaking others. Example: one key for Claude, one for ChatGPT.
Can AI see everything I see when logged in as admin?
No. AI only sees what the API key’s linked Odoo user and access rules allow. An admin’s personal view may show more than the AI key can access.
What does ?db= mean in the URL?
It tells Odoo which database to use when your server hosts more than one. Without it, you often get a 404 error. Always copy the full URL from the API Console.
Should I use OAuth or an API token?
Use OAuth for Claude.ai (browser sign-in). Use an API token (bearer key) for ChatGPT, Cursor, scripts, and most other tools. See the API Keys chapter for token setup.
How long are audit logs kept?
By default, 7 days. Change this under Configuration → Settings → Audit Log Retention. Older logs are deleted automatically.
Can I undo what AI changed in Odoo?
There is no automatic undo. Use Odoo’s record history (chatter) or restore from backup for critical mistakes. Keep delete access disabled for AI keys when possible.
Where is the technical API documentation?
Inside Odoo: Odoo MCP Connection → Configuration → Help. It lists endpoints, tools, and developer details.
Why does the demo portal page work but mine does not?
Demo pages are pre-built and published with a working specification and demo API key. Compare your page’s Page Specification and Published status to the demo setup.
Tips
- Keep a read-only test API key for troubleshooting. Use it in the API Console without risking production data changes.
- Test the demo portal page first:
/mcp-page/demo-contacts?db=your_database– if this works, your server is fine and the issue is with your custom page or key. - Quote the Request ID from Audit Logs when asking IT or your Odoo partner for help – it pinpoints the exact failed request.
When to Escalate
- Contact IT if: HTTPS is not set up, the Odoo server is down, Redis errors appear after enabling it, or reverse proxy / firewall blocks
/mcprequests. - Contact your Odoo partner if: Permissions look correct but data still fails, you need custom domain filters, or generated modules will not install after following all steps here.
You can usually fix yourself: Wrong URL, expired token, unpublished portal page, MCP disabled, rate limits, missing App Access, or OAuth redirect URI not set for Claude.