MCP troubleshooting
Fix common problems when connecting ChatGPT, Codex, Claude or Cursor to the RedERP MCP server: sign-in errors, 401 responses, missing documents, locked records, expired PDF links.
Connecting
| Symptom | Cause | Fix |
|---|---|---|
| The client says the server needs authentication / shows a login button | Expected: the first call answers 401 with OAuth discovery | Click Connect / Sign in and complete the RedERP consent page |
| "Invalid email or password" on the consent page | Wrong credentials, or the user signs in with a one-time code only | Set a password in RedERP (Profile → Security) and retry |
| "Too many failed attempts" | Account lockout after repeated failures (same rule as the web sign-in) | Wait for the lock to expire (1 hour after 10 failures), then retry |
| "This company account is not active" / "This user is not active" | Subscription expired or user disabled | Renew the subscription or ask your administrator to re-activate the user |
invalid_client / Unregistered redirect_uri | The client's callback URL is not on the allowed hosts | Supported clients: ChatGPT, OpenAI Platform, Claude, Cursor and loopback (http://localhost:…) callbacks. Other clients: contact support to allow-list the host |
| "This sign-in request has expired" | More than 10 minutes elapsed on the consent page | Start the connection again from the assistant |
Unknown resource at the token step | The client requested a resource other than https://rederp.ai/mcp | Point the client at the exact URL https://rederp.ai/mcp |
Using the tools
| Symptom | Cause | Fix |
|---|---|---|
| "No invoices match in the current fiscal year" | Lists default to the current fiscal year | Ask for "all years" or give a date range (all_years: true) |
insufficient_scope | The token was granted with sales:read only | Disconnect and reconnect, granting Create sales records |
forbidden / "You don't have permission" | Your RedERP role does not allow the action | Ask your administrator for the permission in Settings → Users & roles |
LOCKED (409) when adding lines or changing status | The document is locked in RedERP | Unlock it in the web app, or leave it as is |
| "Several locations exist — specify location_id" | The company has several warehouses / ledgers and no obvious default | Ask the assistant to list the setup options (get_sales_setup_options) and name the one to use |
| "is not allowed here" when changing a status | Only forward statuses are accepted; cancel / void / reject are refused | Use the RedERP web app for cancellations |
| A conversion is refused | Source status does not allow it (e.g. cancelled quotation, order not confirmed) | Advance the source document first (update_sales_document_status) |
Client name shows a duplicate error on create_client | Client names are unique per company | Search the existing client and reuse it |
PDF links
| Symptom | Cause | Fix |
|---|---|---|
410 Gone — This download link has expired | Links last 7 days | Ask the assistant for a fresh link (get_sales_document_pdf) |
403 — This download link is not valid | The URL was altered or truncated when copied | Copy the full pdf_url including exp and sig |
502 — The PDF could not be generated right now | Temporary rendering issue | Retry in a moment; the printable print_url works meanwhile |
Rate limits
The OAuth endpoints are rate-limited (for example 30 sign-in attempts per 15 minutes per IP, 20 client registrations per hour). A 429 answer means "wait and retry"; it does not affect already issued tokens.
Still stuck?
Collect the client name (ChatGPT web / iOS / Android, Codex, Claude, Cursor…), the time of the attempt and the exact error text, then contact support: rederp.ai/contactus. Developers can reproduce the flow with MCP Inspector and check https://rederp.ai/.well-known/oauth-authorization-server.