License validation fails
"Invalid credentials" — the license key and the panel secret must be the pair issued together for that connection. If you rotated credentials, the plugin still has the old pair: paste the new one. If you only copied one value before leaving the page, rotate to get a fresh pair. If you run several Moodles, check you didn't paste another connection's pair.
"URL mismatch" — the site calling doesn't match the URL registered for the connection. Common when Moodle sits behind a proxy and $CFG-wwwroot differs from the public hostname, or after a domain change. Update the URL from the connection's row in Organization → Moodle and validate again.
The plugin can't reach the panel at all — your Moodle needs outbound HTTPS. Check curl https://lmsmcp.slxd.app from the server and any proxy settings in Moodle.
The site can't be connected
"URL not allowed" — the URL must be public HTTPS with a valid certificate. localhost, private ranges and VPN-only hosts are rejected by design. A staging site works if it's publicly reachable.
Certificate errors — a self-signed or expired certificate fails validation. Fix the certificate; there is no bypass.
No connection slots left — your plan caps how many Moodle sites an organization can connect; the connections page says how many are left. Delete a connection you no longer use, or move up a plan in Organization → Billing.
The assistant says it has no tools
- The client hasn't reloaded its MCP configuration. Restart it.
- The URL is wrong: it must be the connector URL of that connection — your organization's subdomain, then /mcp/lmsmcp/ and the connection's slug. Copy it from the connection's page instead of typing it.
- With a Bearer key: check the header is exactly Authorization: Bearer mcpk_…, and that the key isn't suspended, revoked or expired.
- With OAuth: remove the connector and re-authorize.
The assistant answers about the wrong Moodle, or is refused
Each key belongs to one connection and only works against that connection's connector URL. Using a key of one Moodle against another one's URL is rejected. Check, on the connection's page, that the key you're presenting is listed there.
The connection shows as "Plugin missing" or "Not reachable"
Check now, on the connection's page, asks your Moodle live:
- Plugin missing — Moodle answered, but the connector plugin isn't installed there. Download it with Download the plugin (.zip) and install it.
- Not reachable — Moodle didn't answer: the site is down, the URL changed, or the token of the key used for the check is no longer valid in Moodle.
- No active key — the check needs a token, so create a key for that connection first.
The assistant sees nothing in Moodle
The key works but the underlying Moodle user has no access to what you're asking about. Roles are the outer boundary — a student key can't list a course's participants. Check which user the key was minted for, and whether the key is restricted to read-only, to specific tools or to specific courses. See Keys & permissions.
"Access control exception" when creating or editing
A key's role is checked once, site-wide; Moodle checks permissions per course. An editing-teacher key is allowed the tool, but Moodle refuses it in a course where that user is not an editing teacher. Check that the user the key was minted for:
- is enrolled in that course with a role granting the moodle/course:manageactivities capability (creating and editing activities);
- can see the course, if it is hidden.
Enrolling them in the course, or granting a role with that capability, clears the error. See Keys & permissions.
Calls started failing after they worked
- The key was suspended or revoked, in the panel or from the plugin.
- The connection's credentials were rotated and the plugin hasn't been updated.
- The Moodle user lost the role the key relies on, or was deleted.
- The token was deleted in Moodle under Site administration → Server → Web services → Manage tokens.
The connection's page shows its usage and errors per key and per tool, and Organization → Moodle → Usage shows the whole organization; between the two it usually pinpoints in seconds.
A file won't upload
The URL must return the file, not a page wrapping it. Test with curl -IL url from outside your network. Google Drive, Dropbox and GitHub each need a specific URL form — see Uploading files. If the tool is missing entirely, your plugin is too old; update it.
The chat is missing or refuses to answer
- No MCP key is selected as the AI chat identity in Organization → Moodle. The chat answers about the connection of the key you pick.
- The credit balance can't cover the message — top up in Organization → Credits.
- You hit the rate limit of 10 messages per minute. Wait a moment.
The organization is locked
The trial ended or a payment failed. Subscribe or fix the payment method in Organization → Billing. Nothing is deleted while locked.
Still stuck
Note the exact error, the key's last 4 characters (never the key itself) and the time it happened, and open an issue at github.com/studiolxd/moodle-local_mcpconnector/issues.