Troubleshooting¶

This page collects the most common issues you may run into when running the MCP Server, with a clear “symptom → cause → fix” walkthrough for each.

The AI client cannot connect at all¶

Symptom: The AI client says Unauthorized, Connection refused, Cannot reach server, or hangs forever.

Diagnostic checklist¶

Endpoint enabled? Open MCP Server ‣ Configuration ‣ Server Settings. The master toggle should be Enabled (green).
URL correct? Compare the URL the AI tool is using against the one shown on Server Settings or the Connection form. The URL is built from Settings ‣ Technical ‣ Parameters ‣ System Parameters ‣ web.base.url. If that points at http://localhost:8069, AI clients build the wrong URL.
Connectivity? Run:
```
curl -i https://your-company.odoo.com/odoo/mcp
```
A healthy endpoint returns 401 Unauthorized. 404 or a TCP failure means the URL is wrong or the reverse proxy is not forwarding the path.
Reverse proxy? Make sure your Nginx / HAProxy / Cloud load balancer forwards /odoo/mcp and the /oauth/* endpoints to Odoo.
Firewall / IP allowlist? Check the connection’s Allowed IPs field. If filled, the AI client’s IP must match.

The AI tool says “Unauthorized”¶

Cause

The token, key, or OAuth flow failed authentication.

Fix

Confirm the connection is Active (not Revoked).
Confirm the AI tool is sending the right key — no extra spaces, no truncation, and the Authorization header starts with Bearer followed by exactly one space and then the key.
For OAuth, confirm the access token has not expired — the AI tool refreshes automatically, but a clock skew or a manually edited config can break this.
Check MCP Server ‣ Audit Logs → filter Errors + OAuth events for context.

The AI tool says “Rate limit exceeded”¶

Cause

The connection hit its requests/minute or requests/day ceiling.

Fix

Open the connection form. Under Rate Limits (Bearer) or in the Server Settings defaults, raise the ceiling.
Investigate the source of the burst: a missing cache, a loop in an AI prompt, a misconfigured event subscription.
Use the Audit Logs group-by Tool to see which tool is being hammered.

A specific tool is missing from the AI’s catalog¶

Cause

The tool is either deactivated in the catalog, or excluded from the connection.

Fix

Open MCP Server ‣ Configuration ‣ Tools and confirm the tool is Active.
Open the connection form. Check Allowed Tools — if non-empty, the tool must be listed there.
Check whether the tool depends on an Odoo module that is not installed (e.g. stage_mass_mailing_from_template requires Mass Mailing). The tool itself stays in the catalog but the AI will get a needs_module response.

The AI says an action is “awaiting approval” but the approver doesn’t see it¶

Cause

The approver wasn’t picked correctly, or record rules block them from seeing the request.

Fix

Open the connection form. Confirm the Approver field is set to the right user.
The approver must be either the Assigned Approver or an MCP Administrator. Other users only see requests they filed themselves.
Open MCP Server ‣ Approval Requests, default-filtered to Pending. The request should be there.
If the request is Expired, the approver took too long and the cron expired it. Ask the user to retry — the AI will file a fresh request.

A webhook subscription stopped firing¶

Cause

The endpoint is down, the URL is wrong, or the subscription was deactivated.

Fix

Open the event subscription. Check the Active smart button.
Click the Deliveries smart button to see the per-attempt log. The status badges tell you why each attempt failed.
Inspect the Last delivery status field on the row. If failed, fix the receiving service.
For Slack / Teams / Discord, the destination expects a specific JSON shape — set the Webhook Payload Template.

A Knowledge Layer file is “Failed” or “Skipped”¶

Cause

Extraction crashed, the file is too large, or its mimetype is excluded.

Fix

Open MCP Server ‣ Knowledge ‣ Indexed Sources and find the row.
Failed — click the row to read the error message. Common causes: corrupted PDF, password-protected file, OCR not enabled for image-only PDFs.
Skipped — the mimetype or the parent model is in the Configuration’s exclusion list. Either remove the exclusion or accept that this file is not indexed.
Pending forever — the indexing cron is paused. Flip the master switch on the Configuration page.

Smart Search returns weird results¶

Cause

The embeddings are stale or were never created.

Fix

Open the Knowledge Layer Configuration. If the yellow “Re-index required” banner is showing, your provider / model / dimensions changed.
Click Re-index All in the header and confirm.
The cron rebuilds chunks over the next runs.

The Pulse Report is missing dimensions¶

Cause: The corresponding Odoo module isn’t installed.
Fix: The Pulse Report skips missing modules silently. To get a full report, install the relevant modules (CRM, Mass Mailing, Inventory, Project, etc.). No further config needed.

Sessions list is full of stale rows¶

Cause: Cron is paused or hasn’t run recently.
Fix: The MCP: Cleanup Expired Sessions cron runs daily. If it is paused, enable it from Settings ‣ Technical ‣ Scheduled Actions. Manually deactivate especially old rows from the Sessions list as a one-off cleanup.

Audit logs are growing too quickly¶

Cause

High traffic, payload logging, or long retention.

Fix

Lower the Audit Log Retention (days) in Server Settings.
Turn off Log Payloads unless you need it for a specific investigation.
The MCP: Cleanup Old Audit Logs cron runs daily and prunes anything older than the retention period.

Still stuck?¶

If you’ve worked through every checklist on this page and still cannot explain a failure, open a ticket with TeqStars via the Contact Support section — it lists every available channel, response times, and the exact information to attach so we can reproduce the issue on the first read.